Distribuire su Node.js

EmDash funziona su Node.js 22.16 o superiore. Questa guida utilizza SQLite e l’archiviazione locale per un server. Usa PostgreSQL o libSQL quando più istanze necessitano di un database, e archiviazione compatibile S3 quando i media devono sopravvivere indipendentemente dal disco del server.

Prerequisiti

• Node.js v22.16.0 o superiore
• Un provider di hosting Node.js o VPS

Configurare il sito

Configura EmDash per la distribuzione 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",
			}),
		}),
	],
});

Compilare ed eseguire

1. Compilare il progetto:

   npm run build

2. Avviare il server:

   node ./dist/server/entry.mjs

Il server funziona su http://localhost:4321 per impostazione predefinita. Con la modalità di migrazione predefinita auto, la prima richiesta applica le migrazioni core in sospeso. Un database nuovo riceve anche il seed incorporato. Gestire le migrazioni core del database spiega come migrare prima di riavviare il traffico di produzione.

Attività pianificate

Lo scheduler integrato funziona solo mentre un processo Node.js è in esecuzione. Gestisce pubblicazioni pianificate, attività dei plugin e manutenzione generale.

Mantieni almeno un processo Node.js in esecuzione continua in produzione. Le attività pianificate si mettono in pausa quando ogni processo si ferma o va in sospensione.

Sandbox dei plugin

I plugin del marketplace e quelli elencati sotto sandboxed: [] necessitano di un esecutore sandbox. Su Node.js, l’esecutore è @emdash-cms/sandbox-workerd, che esegue i plugin in un processo figlio workerd. Sandbox dei plugin copre l’installazione, come funziona il processo workerd e le sue modalità di errore.

Scegliere i servizi dati di produzione

Usa il seguente schema quando il database rimane su un volume persistente e i media si spostano nell’archiviazione compatibile S3:

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

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

Docker

Aggiungi un .dockerignore per mantenere piccolo il contesto di build:

node_modules
dist
.git

Crea un 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"]

Il file seed viene letto al momento del build e incorporato nel bundle, quindi non deve essere copiato nell’immagine di runtime. Le migrazioni vengono eseguite alla prima richiesta dopo una distribuzione; il seed si applica solo quando il database non ha collezioni e la configurazione non è stata completata — i dati esistenti non vengono mai sovrascritti.

Compila l’immagine ed esegui il container:

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

Un file Docker Compose gestisce lo stesso container con un volume nominato:

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

volumes:
  emdash-data:

Avvia lo stack in background:

docker compose up -d

Ambiente di runtime

Leggi le credenziali di database e archiviazione dall’ambiente del processo all’avvio del server. Le seguenti variabili supportano la configurazione sopra:

Validazione della chiave di crittografia

EMDASH_ENCRYPTION_KEY attualmente non crittografa i segreti dei plugin né altri dati archiviati. Se la variabile è impostata, EmDash ne verifica il formato all’avvio, ma i valori dei segreti dei plugin rimangono in chiaro nel database.

Se imposti la variabile, genera un valore valido e aggiungi il risultato al tuo ambiente:

npx emdash secrets generate  # aggiungi il risultato al tuo ambiente

Il valore è fornito dall’operatore e non è archiviato nel database. Perderlo non ha impatto sul recupero dei dati perché nessun dato archiviato dipende da esso. Tratta il database e i suoi backup come sensibili perché contengono segreti dei plugin in chiaro.

Opzionale: sovrascritture di valori stabili

EmDash genera automaticamente il segreto HMAC di anteprima e il sale hash IP dei commentatori e li persiste nel database al primo utilizzo. Le variabili d’ambiente seguenti li fissano a un valore che controlli — utile quando un processo separato deve condividere un segreto con il tuo sito principale.

Vedi Segreti e gestione delle chiavi per il formato della chiave, ogni segreto supportato e gli effetti della rotazione o della perdita.

Database e archiviazione

Archiviazione persistente

SQLite richiede archiviazione su disco persistente. Assicurati che la tua piattaforma di hosting fornisca:

• Un volume montato o disco persistente
• Accesso in scrittura alla directory del database
• Meccanismi di backup per il file del database

Fai il backup sia del file SQLite che della directory degli upload. Ferma il processo prima di sostituire qualsiasi cosa durante il recupero. Vedi Backup.

Controlli di salute

Aggiungi un endpoint di controllo salute per i bilanciatori di carico:

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

Questo endpoint dimostra che il processo Node.js può servire route Astro. Non dimostra che il database, il backend di archiviazione, lo stato di migrazione o il sandbox dei plugin sia sano. Verifica queste dipendenze separatamente prima di inviare traffico a una nuova release.

Verificare prima di inviare traffico

Dopo aver avviato un nuovo build, verifica gli stessi servizi runtime che le richieste di produzione utilizzano:

1. Richiedi /health e una pagina di contenuto pubblico. Entrambe devono restituire una risposta di successo.
2. Esegui npx emdash migrate --check dal progetto compilato. Deve riportare nessuna migrazione in sospeso o sconosciuta per il database configurato.
3. Accedi a /_emdash/admin, crea o modifica una bozza usa e getta e pubblicala. Conferma che la pagina pubblica mostra la modifica.
4. Carica un file multimediale usa e getta e apri il suo URL restituito. Elimina il file dopo la verifica.
5. Se il sito usa plugin sandboxed, invoca una route o hook di plugin e conferma che il log del server non ha errori sandbox-non-disponibile o di avvio workerd.

Mantieni la nuova istanza fuori dal bilanciatore di carico finché ogni controllo applicabile non passa.