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.
Prerequisites
Section titled “Prerequisites”- 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:
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 the site
Section titled “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", }), }), ],});Reverse proxies and HTTPS
Section titled “Reverse proxies and HTTPS”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:
export EMDASH_SITE_URL=https://example.comSet 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.
Build and run
Section titled “Build and run”-
Build the project:
Terminal window npm run build -
Start the server:
Terminal window node ./dist/server/entry.mjsSet
EMDASH_ENCRYPTION_KEYand other runtime credentials through the hosting provider’s process environment before starting the server. The standalone Node entry does not load.envautomatically. For a local run that uses the generated.envfile, start it withnode --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
Section titled “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
Section titled “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.
Co-editing
Section titled “Co-editing”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].
Forward WebSocket upgrades
Section titled “Forward WebSocket upgrades”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:
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.
Run several processes
Section titled “Run several processes”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:
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").
Other WebSocket handlers
Section titled “Other WebSocket handlers”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:
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));});Older Node.js releases
Section titled “Older Node.js releases”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.
Stop the process
Section titled “Stop the process”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:
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.
CPU time
Section titled “CPU time”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.
Choose production data services
Section titled “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
Section titled “Docker”Add a .dockerignore to keep the build context small:
node_modulesdist.gitCreate a Dockerfile:
FROM node:22-alpine AS builderWORKDIR /appCOPY package*.json ./RUN npm ciCOPY . .RUN npm run build
FROM node:22-alpineWORKDIR /appCOPY --from=builder /app/dist ./distCOPY --from=builder /app/node_modules ./node_modulesCOPY --from=builder /app/package.json ./
RUN mkdir -p data
ENV HOST=0.0.0.0ENV PORT=4321
EXPOSE 4321CMD ["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-siteA 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 -dRuntime environment
Section titled “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
Section titled “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 environmentThe 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
Section titled “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.
| 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.
Database and storage
Section titled “Database and storage”| 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 |
Persistent storage
Section titled “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
Section titled “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
Section titled “Verify before sending traffic”After starting a new build, verify the same runtime services that production requests use:
- Request
/healthand one public content page. Both must return a successful response. - Run
npx emdash migrate --checkfrom the built project. It must report no pending or unknown migrations for the configured database. - Sign in to
/_emdash/admin, create or edit a disposable draft, and publish it. Confirm that the public page shows the change. - Upload a disposable media file and open its returned URL. Delete the file after verifying it.
- If the site uses sandboxed plugins, invoke one plugin route or hook and confirm that the server log has no sandbox-unavailable or
workerdstartup error. - 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.