Deploy to Node.js

EmDash runs on Node.js 22.16 or later. This guide uses SQLite and local storage for one server. Use PostgreSQL or libSQL when several instances need one database, and S3-compatible storage when media must survive independently of the server disk.

Prerequisites

• Node.js v22.16.0 or higher
• A Node.js hosting provider or VPS

Configure the site

Configure EmDash for Node.js deployment:

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

Build and run

1. Build the project:

   npm run build

2. Start the server:

   node ./dist/server/entry.mjs

   Set EMDASH_ENCRYPTION_KEY and other runtime credentials through the hosting provider’s process environment before starting the server. The standalone Node entry does not load .env automatically. For a local run that uses the generated .env file, start it with node --env-file=.env ./dist/server/entry.mjs.

The server runs on http://localhost:4321 by default. With the default auto migration mode, the first request applies pending core migrations. A fresh database also receives the embedded seed. Manage core database migrations explains how to migrate before restarting production traffic.

Scheduled tasks

The built-in scheduler runs only while a Node.js process is running. It handles scheduled publishing, plugin tasks, and general maintenance.

Keep at least one Node.js process running continuously in production. Scheduled tasks pause when every process stops or sleeps.

Plugin sandbox

Marketplace plugins and the plugins listed under sandboxed: [] need a sandbox runner. On Node.js, the runner is @emdash-cms/sandbox-workerd, which runs plugins in a workerd child process. Plugin Sandbox covers the installation, how the workerd process runs, and its failure modes.

Choose production data services

Use the following pattern when the database stays on a persistent volume and media moves to S3-compatible storage:

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

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

Docker

Add a .dockerignore to keep the build context small:

node_modules
dist
.git

Create a 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"]

The seed file is read at build time and inlined into the bundle, so it does not need to be copied into the runtime image. Migrations run on the first request after a deploy; the seed applies only when the database has no collections and setup hasn’t been completed — existing data is never overwritten.

Build the image and run the container:

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

A Docker Compose file manages the same container with a named volume:

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

volumes:
  emdash-data:

Start the stack in the background:

docker compose up -d

Runtime environment

Read database and storage credentials from the process environment when the server starts. The following variables support the configuration above:

Plugin settings encryption

EMDASH_ENCRYPTION_KEY encrypts plugin settings declared as secrets. A malformed value produces an operator-facing startup message, and plugin secret-setting operations fail until the value is fixed.

Generate a valid value and add the result to the server process environment:

npx emdash secrets generate  # add the result to your environment

The value is operator-provided and is not stored in the database. Keep it in a secret manager and in a separate recovery backup. During rotation, provide the new key first and retain older keys after commas until every plugin secret has been saved again. EmDash does not currently report which key IDs remain in use, so track each resaved credential and verify its integration before removing an old key. Restoring the database without a referenced key leaves the corresponding settings unreadable.

Optional: stable-value overrides

EmDash auto-generates the preview HMAC secret and commenter-IP hash salt and persists them in the database on first use. The env vars below pin them to a value you control — useful when a separate process needs to share a secret with your main site.

See Secrets and key management for the key format, every supported secret, and the effects of rotation or loss.

Database and storage

Persistent storage

SQLite requires persistent disk storage. Ensure your hosting platform provides:

• A mounted volume or persistent disk
• Write access to the database directory
• Backup mechanisms for the database file

Back up both the SQLite file and the upload directory. Stop the process before replacing either during recovery. See Backups.

Health checks

Add a health check endpoint for load balancers:

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

This endpoint proves that the Node.js process can serve Astro routes. It does not prove that the database, storage backend, migration state, or plugin sandbox is healthy. Verify those dependencies separately before sending traffic to a new release.

Verify before sending traffic

After starting a new build, verify the same runtime services that production requests use:

1. Request /health and one public content page. Both must return a successful response.
2. Run npx emdash migrate --check from the built project. It must report no pending or unknown migrations for the configured database.
3. Sign in to /_emdash/admin, create or edit a disposable draft, and publish it. Confirm that the public page shows the change.
4. Upload a disposable media file and open its returned URL. Delete the file after verifying it.
5. If the site uses sandboxed plugins, invoke one plugin route or hook and confirm that the server log has no sandbox-unavailable or workerd startup error.

Keep the new instance out of the load balancer until every applicable check passes.