Auf Node.js bereitstellen

EmDash läuft auf Node.js 22.16 oder neuer. Dieser Leitfaden nutzt SQLite und lokalen Speicher für einen Server. Nutzen Sie PostgreSQL oder libSQL, wenn mehrere Instanzen eine Datenbank brauchen, und S3-kompatiblen Speicher, wenn Medien unabhängig vom Serverdatenträger überleben müssen.

Voraussetzungen

• Node.js v22.16.0 oder höher
• Ein Node.js-Hosting-Anbieter oder VPS

Die Site konfigurieren

Konfigurieren Sie EmDash für die Node.js-Bereitstellung:

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

Bauen und starten

1. Bauen Sie das Projekt:

   npm run build

2. Starten Sie den Server:

   node ./dist/server/entry.mjs

   Setzen Sie EMDASH_ENCRYPTION_KEY und andere Runtime-Credentials über die Prozessumgebung des Hosting-Anbieters, bevor Sie den Server starten. Der standalone Node-Entry lädt .env nicht automatisch. Für einen lokalen Lauf mit der generierten .env-Datei starten Sie mit node --env-file=.env ./dist/server/entry.mjs.

Der Server läuft standardmäßig unter http://localhost:4321. Mit dem Standard-Migrationsmodus auto wendet die erste Anfrage ausstehende Core-Migrationen an. Eine frische Datenbank erhält außerdem den eingebetteten Seed. Manage core database migrations erklärt, wie Sie vor dem Neustart des Produktionsverkehrs migrieren.

Geplante Aufgaben

Der eingebaute Scheduler läuft nur, während ein Node.js-Prozess läuft. Er übernimmt geplantes Veröffentlichen, Plugin-Aufgaben und allgemeine Wartung.

Halten Sie in der Produktion mindestens einen Node.js-Prozess dauerhaft am Laufen. Geplante Aufgaben pausieren, wenn jeder Prozess stoppt oder schläft.

Plugin-Sandbox

Marketplace-Plugins und die unter sandboxed: [] gelisteten Plugins brauchen einen Sandbox-Runner. Unter Node.js ist der Runner @emdash-cms/sandbox-workerd, der Plugins in einem workerd-Kindprozess ausführt. Plugin Sandbox behandelt die Installation, wie der workerd-Prozess läuft und seine Fehlermodi.

Produktions-Datendienste wählen

Nutzen Sie folgendes Muster, wenn die Datenbank auf einem persistenten Volume bleibt und Medien zu S3-kompatiblem Speicher wandern:

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

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

Docker

Fügen Sie eine .dockerignore hinzu, um den Build-Kontext klein zu halten:

node_modules
dist
.git

Erstellen Sie ein 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"]

Die Seed-Datei wird zur Build-Zeit gelesen und in das Bundle eingebettet, daher muss sie nicht in das Runtime-Image kopiert werden. Migrationen laufen bei der ersten Anfrage nach einem Deploy; der Seed wird nur angewendet, wenn die Datenbank keine Collections hat und Setup nicht abgeschlossen wurde — bestehende Daten werden nie überschrieben.

Bauen Sie das Image und starten Sie den Container:

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

Eine Docker-Compose-Datei verwaltet denselben Container mit einem benannten Volume:

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

volumes:
  emdash-data:

Starten Sie den Stack im Hintergrund:

docker compose up -d

Runtime-Umgebung

Lesen Sie Datenbank- und Speicher-Credentials aus der Prozessumgebung, wenn der Server startet. Die folgenden Variablen unterstützen die Konfiguration oben:

Verschlüsselung von Plugin-Einstellungen

EMDASH_ENCRYPTION_KEY verschlüsselt als Secrets deklarierte Plugin-Einstellungen. Ein fehlerhafter Wert erzeugt eine operatorgerichtete Startup-Meldung, und Operationen an Plugin-Secret-Einstellungen scheitern, bis der Wert korrigiert ist.

Generieren Sie einen gültigen Wert und fügen Sie das Ergebnis der Server-Prozessumgebung hinzu:

npx emdash secrets generate  # add the result to your environment

Der Wert wird vom Operator bereitgestellt und nicht in der Datenbank gespeichert. Bewahren Sie ihn in einem Secret-Manager und in einem separaten Recovery-Backup auf. Während der Rotation geben Sie zuerst den neuen Schlüssel an und behalten ältere Schlüssel nach Kommas bei, bis jedes Plugin-Secret erneut gespeichert wurde. EmDash meldet derzeit nicht, welche Schlüssel-IDs noch in Gebrauch sind; verfolgen Sie daher jedes erneut gespeicherte Credential und prüfen Sie seine Integration, bevor Sie einen alten Schlüssel entfernen. Das Wiederherstellen der Datenbank ohne einen referenzierten Schlüssel lässt die entsprechenden Einstellungen unlesbar.

Optional: Overrides für stabile Werte

EmDash generiert das Preview-HMAC-Secret und das Commenter-IP-Hash- Salt automatisch und persistiert sie bei erster Nutzung in der Datenbank. Die Env-Vars unten pinnen sie auf einen Wert, den Sie kontrollieren — nützlich, wenn ein separater Prozess ein Secret mit Ihrer Hauptsite teilen muss.

Siehe Secrets and key management für das Schlüsselformat, jedes unterstützte Secret und die Auswirkungen von Rotation oder Verlust.

Datenbank und Speicher

Persistenter Speicher

SQLite braucht persistenten Festplattenspeicher. Stellen Sie sicher, dass Ihre Hosting-Plattform Folgendes bereitstellt:

• Ein gemountetes Volume oder eine persistente Disk
• Schreibzugriff auf das Datenbankverzeichnis
• Backup-Mechanismen für die Datenbankdatei

Sichern Sie sowohl die SQLite-Datei als auch das Upload-Verzeichnis. Stoppen Sie den Prozess, bevor Sie während der Recovery eines von beiden ersetzen. Siehe Backups.

Health Checks

Fügen Sie einen Health-Check-Endpoint für Load Balancer hinzu:

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

Dieser Endpoint belegt, dass der Node.js-Prozess Astro-Routen bedienen kann. Er belegt nicht, dass Datenbank, Speicher-Backend, Migrationszustand oder Plugin-Sandbox gesund sind. Prüfen Sie diese Abhängigkeiten separat, bevor Sie Traffic an ein neues Release senden.

Vor dem Traffic-Versand prüfen

Nach dem Start eines neuen Builds prüfen Sie dieselben Runtime-Dienste, die Produktionsanfragen nutzen:

1. Rufen Sie /health und eine öffentliche Inhaltsseite an. Beide müssen erfolgreich antworten.
2. Führen Sie npx emdash migrate --check aus dem gebauten Projekt aus. Es muss keine ausstehenden oder unbekannten Migrationen für die konfigurierte Datenbank melden.
3. Melden Sie sich bei /_emdash/admin an, erstellen oder bearbeiten Sie einen Wegwerf-Draft und veröffentlichen Sie ihn. Bestätigen Sie, dass die öffentliche Seite die Änderung zeigt.
4. Laden Sie eine Wegwerf-Mediendatei hoch und öffnen Sie ihre zurückgegebene URL. Löschen Sie die Datei nach der Prüfung.
5. Wenn die Site Sandboxed Plugins nutzt, rufen Sie eine Plugin-Route oder einen Hook auf und bestätigen Sie, dass das Server-Log keinen Sandbox-unavailable- oder workerd-Startup-Fehler hat.

Halten Sie die neue Instanz aus dem Load Balancer, bis jeder zutreffende Check bestanden ist.