Implantar no Node.js

O EmDash roda no Node.js 22.16 ou superior. Este guia usa SQLite e armazenamento local para um servidor. Use PostgreSQL ou libSQL quando várias instâncias precisarem de um banco de dados, e armazenamento compatível com S3 quando a mídia precisar sobreviver independentemente do disco do servidor.

Pré-requisitos

• Node.js v22.16.0 ou superior
• Um provedor de hospedagem Node.js ou VPS

Configurar o site

Configure o EmDash para implantação Node.js:

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import emdash, { local, s3 } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	output: "server",
	adapter: node({ mode: "standalone" }),
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data/emdash.db" }),
			storage: local({
				directory: "./data/uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

Compilar e executar

1. Compilar o projeto:

   npm run build

2. Iniciar o servidor:

   node ./dist/server/entry.mjs

O servidor roda em http://localhost:4321 por padrão. Com o modo de migração padrão auto, a primeira requisição aplica as migrações core pendentes. Um banco de dados novo também recebe o seed embutido. Gerenciar migrações de banco de dados core explica como migrar antes de reiniciar o tráfego de produção.

Tarefas agendadas

O agendador embutido roda apenas enquanto um processo Node.js está em execução. Ele lida com publicações agendadas, tarefas de plugins e manutenção geral.

Mantenha pelo menos um processo Node.js rodando continuamente em produção. Tarefas agendadas pausam quando todos os processos param ou entram em suspensão.

Sandbox de plugins

Plugins do marketplace e os listados em sandboxed: [] precisam de um executor sandbox. No Node.js, o executor é @emdash-cms/sandbox-workerd, que roda plugins em um processo filho workerd. Sandbox de plugins cobre a instalação, como o processo workerd roda e seus modos de falha.

Escolher serviços de dados de produção

Use o seguinte padrão quando o banco de dados permanece em um volume persistente e a mídia se move para armazenamento compatível com S3:

import emdash, { s3 } from "emdash/astro";

export default defineConfig({
	integrations: [
			emdash({
				database: sqlite({ url: `file:${process.env.DATABASE_PATH}` }),
				storage: s3(),
		}),
	],
});

Docker

Adicione um .dockerignore para manter o contexto de build pequeno:

node_modules
dist
.git

Crie um Dockerfile:

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

RUN mkdir -p data

ENV HOST=0.0.0.0
ENV PORT=4321

EXPOSE 4321
CMD ["node", "./dist/server/entry.mjs"]

O arquivo seed é lido em tempo de build e incorporado no bundle, então não precisa ser copiado para a imagem de runtime. Migrações rodam na primeira requisição após uma implantação; o seed só se aplica quando o banco não tem coleções e a configuração não foi completada — dados existentes nunca são sobrescritos.

Compile a imagem e execute o container:

docker build -t my-emdash-site .
docker run -p 4321:4321 -v emdash-data:/app/data my-emdash-site

Um arquivo Docker Compose gerencia o mesmo container com um volume nomeado:

services:
  emdash:
    build: .
    ports:
      - "4321:4321"
    volumes:
      - emdash-data:/app/data
    restart: unless-stopped

volumes:
  emdash-data:

Inicie a stack em segundo plano:

docker compose up -d

Ambiente de runtime

Leia as credenciais de banco de dados e armazenamento do ambiente do processo quando o servidor iniciar. As seguintes variáveis suportam a configuração acima:

Validação da chave de criptografia

EMDASH_ENCRYPTION_KEY atualmente não criptografa segredos de plugins ou outros dados armazenados. Se a variável estiver definida, o EmDash verifica seu formato durante a inicialização, mas os valores dos segredos de plugins permanecem em texto simples no banco.

Se definir a variável, gere um valor válido e adicione o resultado ao seu ambiente:

npx emdash secrets generate  # adicionar o resultado ao seu ambiente

O valor é fornecido pelo operador e não é armazenado no banco. Perdê-lo não tem impacto na recuperação de dados porque nenhum dado armazenado depende dele. Trate o banco e seus backups como sensíveis porque contêm segredos de plugins em texto simples.

Opcional: substituições de valores estáveis

O EmDash gera automaticamente o segredo HMAC de prévia e o salt de hash de IP do comentarista e os persiste no banco no primeiro uso. As variáveis de ambiente abaixo os fixam a um valor que você controla — útil quando um processo separado precisa compartilhar um segredo com seu site principal.

Veja Segredos e gerenciamento de chaves para o formato da chave, cada segredo suportado e os efeitos de rotação ou perda.

Banco de dados e armazenamento

Armazenamento persistente

SQLite requer armazenamento em disco persistente. Certifique-se de que sua plataforma de hospedagem forneça:

• Um volume montado ou disco persistente
• Acesso de escrita ao diretório do banco de dados
• Mecanismos de backup para o arquivo do banco

Faça backup tanto do arquivo SQLite quanto do diretório de uploads. Pare o processo antes de substituir qualquer um durante a recuperação. Veja Backups.

Verificações de saúde

Adicione um endpoint de verificação de saúde para balanceadores de carga:

export const GET = () => {
  return new Response("OK", { status: 200 });
};

Este endpoint prova que o processo Node.js pode servir rotas Astro. Não prova que o banco, o backend de armazenamento, o estado de migração ou o sandbox de plugins esteja saudável. Verifique essas dependências separadamente antes de enviar tráfego para uma nova versão.

Verificar antes de enviar tráfego

Após iniciar um novo build, verifique os mesmos serviços runtime que as requisições de produção usam:

1. Requisite /health e uma página de conteúdo público. Ambas devem retornar uma resposta bem-sucedida.
2. Execute npx emdash migrate --check a partir do projeto compilado. Deve reportar nenhuma migração pendente ou desconhecida para o banco configurado.
3. Faça login em /_emdash/admin, crie ou edite um rascunho descartável e publique-o. Confirme que a página pública mostra a alteração.
4. Faça upload de um arquivo de mídia descartável e abra sua URL retornada. Delete o arquivo após verificar.
5. Se o site usa plugins sandboxed, invoque uma rota ou hook de plugin e confirme que o log do servidor não tem erros de sandbox-indisponível ou inicialização do workerd.

Mantenha a nova instância fora do balanceador de carga até que cada verificação aplicável passe.