Deploy su Node.js

EmDash funziona su qualsiasi piattaforma di hosting Node.js 22+. Questa guida utilizza SQLite con storage locale o compatibile S3; libSQL e PostgreSQL funzionano allo stesso modo su Node.js — vedi Opzioni database.

Prerequisiti

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

Configurazione

Configura EmDash per il deployment 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. Compila il progetto:

   npm run build

2. Avvia il server:

   node ./dist/server/entry.mjs

Il server viene eseguito su http://localhost:4321 per impostazione predefinita. Le migrazioni vengono applicate alla prima richiesta. Se il database è vuoto e il setup non è stato completato, anche il tuo file seed (o quello predefinito integrato se non ne hai uno) viene applicato a quella prima richiesta.

Storage di produzione

Per la produzione, utilizza storage compatibile S3 invece del filesystem locale:

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

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: `file:${process.env.DATABASE_PATH}` }),
			storage: s3({
				endpoint: process.env.S3_ENDPOINT,
				bucket: process.env.S3_BUCKET,
				accessKeyId: process.env.S3_ACCESS_KEY_ID,
				secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
				publicUrl: process.env.S3_PUBLIC_URL, // Optional CDN URL
			}),
		}),
	],
});

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 della compilazione e incorporato nel bundle, quindi non deve essere copiato nell’immagine di runtime. Le migrazioni vengono eseguite alla prima richiesta dopo un deploy; il seed si applica solo quando il database non ha collezioni e il setup non è stato completato — 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

Variabili d’ambiente

Consigliato: chiave di crittografia

EMDASH_ENCRYPTION_KEY è la chiave per crittografare i segreti dei plugin a riposo. La chiave viene convalidata all’avvio; la crittografia dei segreti dei plugin la utilizza una volta abilitata. Impostala ad ogni deployment in modo che i segreti siano protetti senza una successiva modifica di configurazione.

Genera una chiave e aggiungi il risultato al tuo ambiente:

npx emdash secrets generate  # add the result to your environment

La chiave è fornita da te e non viene mai memorizzata nel database; solo il testo cifrato lo è. Effettua il backup in un luogo durevole (un gestore di password, KMS o l’archivio segreti del tuo team) — perderla significa perdere ogni segreto crittografato con essa.

Opzionale: sovrascritture di valori stabili

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

Database e storage

Storage persistente

SQLite richiede storage 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

Controlli di salute

Aggiungi un endpoint di controllo di salute per i load balancer:

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

Configura la tua piattaforma per verificare /health per le sonde di liveness.