Déployer sur Node.js

EmDash fonctionne sur toute plateforme d’hébergement Node.js 22+. Ce guide utilise SQLite avec un stockage local ou compatible S3 ; libSQL et PostgreSQL fonctionnent de la même manière sur Node.js — voir Options de base de données.

Prérequis

• Node.js v22.12.0 ou supérieur
• Un fournisseur d’hébergement Node.js ou un VPS

Configuration

Configurez EmDash pour le déploiement 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",
			}),
		}),
	],
});

Compiler et lancer

1. Compiler le projet :

   npm run build

2. Démarrer le serveur :

   node ./dist/server/entry.mjs

Le serveur fonctionne sur http://localhost:4321 par défaut. Les migrations sont appliquées lors de la première requête. Si la base de données est vide et que la configuration n’a pas été complétée, votre fichier seed (ou le seed par défaut intégré si vous n’en avez pas) est également appliqué lors de cette première requête.

Stockage de production

Pour la production, utilisez un stockage compatible S3 au lieu du système de fichiers local :

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 optionnelle
			}),
		}),
	],
});

Docker

Ajoutez un .dockerignore pour garder le contexte de build petit :

node_modules
dist
.git

Créez 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"]

Le fichier seed est lu au moment du build et intégré dans le bundle, il n’a donc pas besoin d’être copié dans l’image de runtime. Les migrations s’exécutent lors de la première requête après un déploiement ; le seed ne s’applique que lorsque la base de données n’a pas de collections et que la configuration n’a pas été complétée — les données existantes ne sont jamais écrasées.

Si vous rencontrez cette erreur, installez la chaîne d’outils dans l’étape builder avant npm ci :

# Images basées sur Alpine (node:22-alpine)
RUN apk add --no-cache python3 make g++

# Images basées sur Debian (node:22-slim)
RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \
    && rm -rf /var/lib/apt/lists/*

Compiler l’image et lancer le conteneur :

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

Un fichier Docker Compose gère le même conteneur avec un volume nommé :

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

volumes:
  emdash-data:

Démarrer la pile en arrière-plan :

docker compose up -d

Variables d’environnement

Recommandé : clé de chiffrement

EMDASH_ENCRYPTION_KEY est la clé pour chiffrer les secrets de plugins au repos. La clé est validée au démarrage ; le chiffrement des secrets de plugins l’utilise une fois activé. Configurez-la à chaque déploiement pour que les secrets soient protégés sans changement de configuration ultérieur.

Générez une clé et ajoutez le résultat à votre environnement :

npx emdash secrets generate  # ajoutez le résultat à votre environnement

La clé est fournie par vous et jamais stockée dans la base de données ; seul le texte chiffré est stocké. Sauvegardez-la dans un endroit durable (gestionnaire de mots de passe, KMS ou magasin de secrets de votre équipe) — la perdre signifie perdre chaque secret chiffré avec elle.

Optionnel : surcharges de valeurs stables

EmDash génère automatiquement le secret HMAC de preview et le sel de hachage d’IP des commentateurs et les persiste dans la base de données à la première utilisation. Les variables d’environnement ci-dessous les fixent à une valeur que vous contrôlez — utile quand un processus séparé doit partager un secret avec votre site principal.

Base de données et stockage

Stockage persistant

SQLite nécessite un stockage disque persistant. Assurez-vous que votre plateforme d’hébergement fournit :

• Un volume monté ou un disque persistant
• Un accès en écriture au répertoire de la base de données
• Des mécanismes de sauvegarde pour le fichier de base de données

Health Checks

Ajoutez un endpoint de health check pour les load balancers :

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

Configurez votre plateforme pour vérifier /health pour les sondes de vivacité.