Skip to content

Deploy to Node.js

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.

  • Node.js v22.23.4 or higher (v22.16.0 is enough on Astro 7.3 or earlier)
  • A Node.js hosting provider or VPS
  • SQLite FTS5 support in the Node.js build when using the built-in SQLite adapter

Search requires FTS5. Its availability depends on how Node.js was compiled, not just the Node.js or SQLite version. Check the exact Node binary used by your server:

Terminal window
node --input-type=module -e 'import { DatabaseSync } from "node:sqlite"; const db = new DatabaseSync(":memory:"); db.exec("CREATE VIRTUAL TABLE probe USING fts5(x)"); db.close(); console.log("FTS5 available");'

If the command reports no such module: fts5, switch to a Node.js build with FTS5 support. Search requests return 503 SEARCH_UNAVAILABLE until FTS5 is available. After switching builds, enable search for collections whose search setup failed.

Configure EmDash for Node.js deployment:

astro.config.mjs
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",
}),
}),
],
});

When the Node process sits behind a reverse proxy that terminates TLS, internal requests arrive over HTTP while visitors reach the site over HTTPS. Set the public origin with EMDASH_SITE_URL or SITE_URL so EmDash builds correct absolute URLs:

Terminal window
export EMDASH_SITE_URL=https://example.com

Set the variable both where npm run build runs and where the server runs. The build uses it to enable image optimization for locally stored media. If it is missing at build time, images are served as unoptimized originals instead of through Astro’s /_image endpoint. See siteUrl for how EmDash resolves the public origin.

The proxy must also forward WebSocket upgrades for co-editing. See Forward WebSocket upgrades.

  1. Build the project:

    Terminal window
    npm run build
  2. Start the server:

    Terminal window
    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.

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.

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.

Co-editing is off by default. Set coEditing: true to turn it on. On Node.js, each entry’s room runs inside a site process. EmDash takes WebSocket upgrades on the room path, /_emdash/api/content/{collection}/{id}/room after any base path, from the HTTP server that serves Astro. Rooms store their state in the site database, in the _emdash_rooms and _emdash_room_updates tables, and the process keeps each open room’s document in memory.

Rooms run when the site uses @astrojs/node with an HTTP/1.1 node:http or node:https server:

  • in standalone mode;
  • in middleware mode, under a server such as Express or Fastify;
  • under astro preview; and
  • under astro dev, beside Vite’s hot-reload socket.

Sites on other adapters, and node:cluster workers, use single-editor mode. A process on another kind of server also gives joins single-editor mode, starting a minute after its first join. Room log messages start with [co-editing].

A reverse proxy in front of the site must forward WebSocket upgrades on room paths. Otherwise, each browser session switches to single-editor mode after its first three connections fail, and the server logs a warning such as [co-editing] posts:01JV5Z7Q3W8E2N6R4T9Y0A1B2C: a client's sockets didn't open, so it edits in single-editor mode.

The following nginx configuration forwards room paths, with their upgrades, to a site on port 4321. In the room location, also set any headers that the rest of the site gets, such as X-Forwarded-Proto:

/etc/nginx/conf.d/emdash.conf
map $http_upgrade $connection_upgrade {
default upgrade;
"" close;
}
server {
# listen, server_name and TLS settings
location ~ ^/_emdash/api/content/[^/]+/[^/]+/room$ {
proxy_pass http://127.0.0.1:4321;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
location / {
proxy_pass http://127.0.0.1:4321;
proxy_set_header Host $host;
}
}

Add the site’s base path to the start of the room location if it has one. nginx’s WebSocket proxying guide explains the upgrade headers; other proxies need equivalent settings.

EmDash pings each room socket every 30 seconds, so a proxy that closes idle connections must wait longer than that. nginx waits 60 seconds by default.

Several Node.js processes can serve one site from a shared database. Each entry’s room runs in one of them at a time: the first process to open it claims it in the database. People co-edit only when both their join request and their WebSocket, which use the same path, reach that process.

Route each room path to one process, or leave co-editing off. The following nginx upstreams pick one of two processes by hashing the path:

/etc/nginx/conf.d/emdash.conf
upstream emdash {
server 127.0.0.1:4321;
server 127.0.0.1:4322;
}
upstream emdash_rooms {
hash $uri consistent;
server 127.0.0.1:4321;
server 127.0.0.1:4322;
}

With these upstreams, the room location from Forward WebSocket upgrades uses proxy_pass http://emdash_rooms;, and location / uses proxy_pass http://emdash;.

Without routing by path, people whose requests reach another process wait read-only, without Take over, while the room is open in the first one. With round-robin routing, someone editing alone can need several tries to join, because a missed upgrade holds the room’s claim for up to a minute.

Writes that another process handles reach the room late, at its next save or join, even with routing by path:

  • Co-editors aren’t told to reload values that save separately, such as SEO settings, so one saved from an older form can overwrite a newer change.
  • Publishing, scheduling or discarding changes through another process uses the last saved draft, and restoring a version there merges like any other write.

node:cluster workers, including PM2’s cluster mode, use single-editor mode, because the cluster’s primary process hands out connections without seeing their paths. To co-edit under PM2, use fork mode (exec_mode: "fork").

EmDash adds one upgrade listener to the site’s server. Any other upgrade handler on that server must leave room paths alone. Handlers that answer every upgrade, such as a ws server created with { server }, express-ws and @fastify/websocket, don’t. Replace such a handler with a ws server created with noServer: true that you hand only your own paths, or leave co-editing off.

The following Express server runs a site built with node({ mode: "middleware" }) and passes upgrades on /live to its own ws server, leaving room paths to EmDash:

server.mjs
import express from "express";
import { WebSocketServer } from "ws";
import { handler as ssrHandler } from "./dist/server/entry.mjs";
const app = express();
app.use("/", express.static("dist/client/"));
app.use(ssrHandler);
const server = app.listen(8080);
const live = new WebSocketServer({ noServer: true });
server.on("upgrade", (request, socket, head) => {
if (new URL(request.url, "http://localhost").pathname !== "/live") return;
live.handleUpgrade(request, socket, head, (ws) => live.emit("connection", ws, request));
});

On Node.js 22.21 or later and 24.9 or later, EmDash sets the server’s shouldUpgradeCallback, keeping any callback the site set, so that the server hands room upgrades to EmDash and handles every other request as it would without co-editing. Node.js 22.16 to 22.20, 23, and 24.0 to 24.8 have no shouldUpgradeCallback. On those releases, a server whose only upgrade listener is EmDash’s answers upgrade requests on other paths, such as Upgrade: h2c, with 404. Without co-editing, the server serves them as plain requests. If a client of the site sends such requests, upgrade Node.js or leave co-editing off.

While a process has rooms open, EmDash handles SIGTERM and SIGINT ahead of other listeners. On either signal, the process stops accepting joins, and its rooms save their edits and close their connections. The process then stops as it would have, at most 5 seconds later.

Give the process more than 5 seconds to stop. Docker waits 10 seconds by default. PM2 waits 1.6 seconds, so raise its kill_timeout:

ecosystem.config.cjs
module.exports = {
apps: [
{
name: "my-emdash-site",
script: "./dist/server/entry.mjs",
kill_timeout: 6000,
},
],
};

If the process is killed sooner, or another signal handler exits first, its rooms recover as after a crash. Editors of those entries wait read-only until the process’s claims expire, up to a minute later. Edits that the room hadn’t stored come back from the editors that hold them.

A room saves 2 seconds after the latest change, and at least every 10 seconds while people keep typing, however many people edit. A write from outside the editor, such as a REST API or MCP update, notifies the entry’s room, which merges the change. The following table lists the CPU time each of these took for one room on Node.js on Apple Silicon, with an in-memory SQLite database. Each time includes the database work. About two thirds of a save is the site’s own draft save, which an autosave also runs.

Work Median 95th percentile
Save a 2,000-word entry after a small edit 2.27 ms 3.83 ms
Merge a write that changed the title 0.80 ms 1.89 ms
Merge a write that changed a 2,000-word body 1.19 ms 3.06 ms
Answer a notification with nothing to merge 0.67 ms 1.21 ms

A room that isn’t open ignores notifications, so they take almost no CPU time.

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

astro.config.mjs
import emdash, { s3 } from "emdash/astro";
export default defineConfig({
integrations: [
emdash({
database: sqlite({ url: `file:${process.env.DATABASE_PATH}` }),
storage: s3(),
}),
],
});

Add a .dockerignore to keep the build context small:

.dockerignore
node_modules
dist
.git

Create a Dockerfile:

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:

Terminal window
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:

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

Start the stack in the background:

Terminal window
docker compose up -d

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

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:

Terminal window
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.

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.

Variable Description
EMDASH_PREVIEW_SECRET Override for the auto-generated preview HMAC secret.
EMDASH_IP_SALT Override for the auto-generated commenter-IP hash salt.
EMDASH_AUTH_SECRET Optional. If set, used as the IP-salt source (unless EMDASH_IP_SALT is also set, which takes precedence), keeping commenter-IP hashes stable for installs that already rely on it. Leave it unset for a new deployment.

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

Variable Description Example
EMDASH_SITE_URL Public site origin https://example.com
DATABASE_PATH Path to SQLite database /data/emdash.db
HOST Server host 0.0.0.0
PORT Server port 4321
S3_ENDPOINT S3 endpoint URL https://xxx.r2.cloudflarestorage.com
S3_BUCKET S3 bucket name my-media-bucket
S3_ACCESS_KEY_ID S3 access key AKIA...
S3_SECRET_ACCESS_KEY S3 secret key ...
S3_REGION S3 region auto
S3_PUBLIC_URL Public URL for media https://cdn.example.com

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.

Add a health check endpoint for load balancers:

src/pages/health.ts
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.

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.
  6. If co-editing is on, open the disposable entry in two browser windows and type in one. The text must appear in the other, and the server log must have no [co-editing] warning.

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

A site created through the setup wizard starts in staging, hidden from search engines. When it’s ready to be found, go live.