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 su 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 è in esecuzione su http://localhost:4321 per impostazione predefinita. Le migrazioni vengono applicate alla prima richiesta. Se il database è vuoto e la configurazione non è stata completata, il tuo file seed (o quello predefinito integrato se non ne hai uno) viene applicato anche alla prima richiesta.

Storage di produzione

Per la produzione, usa 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, // URL CDN opzionale
			}),
		}),
	],
});

Docker

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

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 ha bisogno di 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 la configurazione non è stata completata — i dati esistenti non vengono mai sovrascritti.

Se incontri quell’errore, installa la toolchain nella fase builder prima di npm ci:

# Immagini basate su Alpine (node:22-alpine)
RUN apk add --no-cache python3 make g++

# Immagini basate su Debian (node:22-slim)
RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \
    && rm -rf /var/lib/apt/lists/*

Compilare l’immagine ed eseguire 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 con nome:

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

volumes:
  emdash-data:

Avviare lo stack in background:

docker compose up -d

Variabili d’ambiente

Consigliato: chiave di crittografia

EMDASH_ENCRYPTION_KEY è la chiave per crittografare i secret dei plugin a riposo. La chiave viene validata all’avvio; la crittografia dei secret dei plugin la usa una volta abilitata. Impostala ad ogni deployment così i secret sono protetti senza un successivo cambio di configurazione.

Genera una chiave e aggiungi il risultato al tuo ambiente:

npx emdash secrets generate  # aggiungi il risultato al tuo ambiente

La chiave è fornita da te e mai memorizzata nel database; solo il testo cifrato viene memorizzato. Eseguine il backup in un luogo durevole (gestore di password, KMS o store di secret del tuo team) — perderla significa perdere ogni secret crittografato con essa.

Opzionale: override di valori stabili

EmDash genera automaticamente il secret HMAC di preview e il salt dell’hash IP dei commentatori e li persiste nel database al primo utilizzo. Le variabili d’ambiente sotto li fissano a un valore che controlli tu — utile quando un processo separato deve condividere un secret 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

Health Check

Aggiungi un endpoint di health check 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.