EmDash

EmDash is an open source, full-stack CMS built on Astro and written in TypeScript. It provides a WordPress-like admin panel for pages, posts, media, menus, and taxonomies, along with drafts, revisions, scheduled publishing, a sandboxed plugin system, a WordPress importer, and an MCP server for AI agents. EmDash runs as a server-rendered Astro application, so you deploy it to Sevalla with Application Hosting. Static Site Hosting is not supported because the admin panel, API, and authentication all require a running server.

EmDash works on Sevalla, but its starter templates need a few adjustments first: the Node.js adapter, the PostgreSQL package, and the S3 storage packages. For the best experience, we created a Sevalla-flavored template that already includes these changes, along with sessions in PostgreSQL, edge cache purging, PostgreSQL full-text search, health checks, and a production-ready Dockerfile. Take a look at the EmDash template for Sevalla.

Sevalla template

The EmDash template for Sevalla is EmDash’s official blog template (posts, pages, categories, tags, search, RSS, comments, and dark mode) with the hosting layer adapted for Sevalla. It uses the following Sevalla products:

Sevalla product	What it does
Application Hosting	Runs the Astro/EmDash server from the included `Dockerfile`. The container is stateless, so you can scale it horizontally.
Managed PostgreSQL	Stores content, users, settings, and sessions, and powers post search with PostgreSQL full-text search.
Object Storage	Stores uploaded media. The admin panel uploads directly to the bucket with presigned URLs, and visitors load media from the bucket’s public domain.
Edge Caching	Serves rendered pages from Cloudflare’s global network. When an editor publishes, the app purges the edge cache through the Sevalla API.
CDN	Serves the hashed JS, CSS, and font assets under `/_astro/` with long-term immutable caching.

The template’s README walks through creating the database, bucket, and application step by step. If you start from your own EmDash project instead, the rest of this guide explains the changes you need to make.

Application Hosting

Required adjustments

EmDash’s starter templates target either Cloudflare Workers (with D1 and R2 bindings) or a single Node.js server (with SQLite and media files on the local disk). Neither works on Sevalla without changes:

Node.js adapter - Sevalla runs your application as a Node.js server, so you need @astrojs/node in standalone mode instead of the Cloudflare adapter.
PostgreSQL - SQLite stores the database in a file on the local disk. Application containers on Sevalla use ephemeral storage, so the database is lost on every deploy and can’t be shared between instances. Use a Sevalla PostgreSQL database instead, which requires the pg package.
S3-compatible storage - Uploaded media must live outside the container for the same reason. Use Sevalla Object Storage through EmDash’s s3() adapter, which requires the AWS SDK packages.

Install the required packages:

npm install @astrojs/node pg @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Although you can attach persistent storage to keep SQLite and local uploads, this limits your application to a single instance. We recommend PostgreSQL and Object Storage so you can scale horizontally and deploy without downtime.

Configuration

We recommend the following best practices for configuring EmDash on Sevalla:

Use output: "server" with the Node.js adapter in standalone mode.
Connect the application to PostgreSQL through an internal connection in the same region for lower latency and better security.
Read database and storage credentials from runtime environment variables, and never commit them to your repository or bake them into the image.
Store Astro sessions outside the container, for example in PostgreSQL or Redis, so editors stay signed in across deploys and instances.
Set EMDASH_SITE_URL to your public URL before running the setup wizard, because passkeys are tied to this origin.
Generate an EMDASH_ENCRYPTION_KEY with npx emdash secrets generate and keep a copy in a password manager.
Set trustedProxyHeaders so EmDash uses the real client IP for rate limiting.
Use toolbar: "client" so public HTML is the same for every visitor and can be cached at the edge.

The following is an example astro.config.mjs file for deploying EmDash on Sevalla:

// astro.config.mjs
import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import react from "@astrojs/react";
import emdash, { s3 } from "emdash/astro";
import { postgres } from "emdash/db";

export default defineConfig({
  output: "server",
  adapter: node({
    mode: "standalone", // Required for Sevalla deployments
  }),
  // Sevalla terminates TLS at Cloudflare and forwards requests over HTTP.
  // Trusting the forwarded protocol lets Astro and EmDash see the public https:// URL.
  security: {
    allowedDomains: [{ protocol: "https" }],
  },
  integrations: [
    react(),
    emdash({
      // Sevalla managed PostgreSQL
      database: postgres({
        connectionString: process.env.DATABASE_URL,
        pool: { max: 10, connectionTimeoutMillis: 10_000 },
      }),
      // Sevalla Object Storage, configured from the S3_* environment variables
      storage: s3(),
      toolbar: "client",
      // Cloudflare, in front of every Sevalla application, sets CF-Connecting-IP
      trustedProxyHeaders: ["cf-connecting-ip", "x-real-ip"],
    }),
  ],
});

EmDash writes the options passed to postgres() into the build output. With the configuration above, DATABASE_URL must be available during the build process, and its value is stored in the built application. To keep credentials out of the build, load the connection string at runtime through a custom database entrypoint, as the Sevalla template does.

Environment variables

Add the following environment variables to your application:

Variable	Value
`DATABASE_URL`	The internal connection URL of your PostgreSQL database. When you add an internal connection, select Add environment variables to the application and rename the connection URL key to `DATABASE_URL`.
`EMDASH_SITE_URL`	The public URL of your site, for example, `https://emdash-abc12.sevalla.app`.
`EMDASH_ENCRYPTION_KEY`	The output of `npx emdash secrets generate`. Encrypts plugin secrets stored in the database.
`S3_ENDPOINT`	The endpoint of your Object Storage bucket.
`S3_BUCKET`	The name of your bucket.
`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY`	The access key and secret key of your bucket.
`S3_REGION`	`auto`
`S3_PUBLIC_URL`	Optional. The public domain of your bucket, for example, `https://my-bucket.sevalla.storage`. If empty, media is served through the application.

You can find the endpoint, bucket name, and keys on your bucket’s Settings page.

Object Storage

The admin panel uploads media directly from the browser to the bucket with presigned URLs. To allow this, configure your bucket as follows:

Under Settings > CORS Policy, create a rule with your application URL as the allowed origin, PUT, GET, and HEAD as the allowed methods, and content-type as the allowed header. Add your custom domains to the rule later.
Optionally, enable Public access to serve media directly from the bucket’s sevalla.storage domain, and set it as S3_PUBLIC_URL.

Recent versions of the AWS SDK add checksums to presigned upload URLs by default, which Sevalla Object Storage can reject. Set the following environment variables at runtime to only send checksums when an operation requires them:

AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED
AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED

EmDash’s automatic backups write JSON archives to the media bucket under backups/. If your bucket has public access enabled, anyone who guesses the file name can download them. Leave EmDash’s automatic backups off and rely on Sevalla’s database backups, or keep the bucket private and leave S3_PUBLIC_URL empty.

Containerization

Dockerfile

The build for Dockerfiles is fully customizable. The following is an example Dockerfile for EmDash:

# Dockerfile for EmDash on Sevalla

FROM node:24-slim AS deps
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci --no-audit --no-fund

FROM deps AS build
COPY . .

# DATABASE_URL is only needed here if your database configuration reads it at build time
ARG DATABASE_URL
RUN npm run build \
    && npm prune --omit=dev --no-audit --no-fund

FROM node:24-slim AS runtime
WORKDIR /app

ENV NODE_ENV=production \
    HOST=0.0.0.0 \
    PORT=8080

# Only send S3 checksums when required (see the Object Storage section)
ENV AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED \
    AWS_RESPONSE_CHECKSUM_VALIDATION=WHEN_REQUIRED

COPY --from=build --chown=node:node /app/package.json /app/package-lock.json ./
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
COPY --from=build --chown=node:node /app/.emdash ./.emdash

USER node
EXPOSE 8080

CMD ["node", "./dist/server/entry.mjs"]

The seed file is inlined into the build, so you don’t need to copy it into the runtime image.

Nixpacks

You can customize the Nixpacks build process by defining a nixpacks.toml file and using Nixpacks-specific environment variables. The following is an example nixpacks.toml configuration:

[phases.install]
cmds = ["npm ci"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "node ./dist/server/entry.mjs"

EmDash requires Node.js 22.16 or later. Set the Node.js version with the engines field in your package.json or with the NIXPACKS_NODE_VERSION environment variable.

Buildpacks

If you’re using Buildpacks, you cannot modify the underlying build phases directly. Buildpacks run the build script in your package.json and start the application with the start script:

"scripts": {
  "build": "astro build",
  "start": "node ./dist/server/entry.mjs"
},
"engines": {
  "node": ">=22.16.0"
}

Database migrations

By default, EmDash applies pending core migrations on the first request after a deploy, and seeds a fresh database with your seed file. To run migrations once per deploy before new instances receive traffic, add a job process with the Start policy set to Before deployment and a start command that runs npx emdash migrate. emdash migrate refuses to apply migrations outside an interactive terminal unless you pass the fingerprint of the target database. The Sevalla template includes a migrate script that reads the target database fingerprint and applies migrations non-interactively, so you can use npm run migrate as the job’s start command. EmDash creates and alters its own tables as you change the content model, so the database user must own the database. The default user Sevalla creates for a PostgreSQL database meets this requirement.

CDN

Sevalla provides a premium, Cloudflare-powered CDN for Application Hosting at no additional cost. To get the most out of Sevalla’s CDN when deploying your EmDash site, we recommend the following best practices:

Enable the CDN for all production applications.
Leverage Astro’s fingerprinted assets in the _astro/ directory for safe long-term caching.
Serve uploaded media from your bucket’s public domain instead of through the application.
Upload web-sized images, because EmDash on Node.js serves original uploads without resizing.
Purge the CDN cache after deploying critical updates to avoid serving stale content.

Edge caching

Edge caching stores rendered pages on Cloudflare’s 260+ global data centers, delivering responses from the location nearest to each visitor. A CMS is a good fit for edge caching because most pages change only when an editor publishes. To use it with EmDash, we recommend the following best practices:

Only cache public pages. Never cache the admin panel, API, and authentication routes under /_emdash/, previews, or any response for a signed-in user.
Use toolbar: "client" so the HTML of public pages is the same for every visitor.
Purge the edge cache whenever content changes, so visitors see new content immediately.
Monitor cache efficiency using the cf-cache-status header returned by Cloudflare.

`Cache-Control`

With Sevalla’s Cloudflare integration, Cache-Control headers are respected at the edge. The following directives are useful for EmDash sites:

public, max-age=0, s-maxage=3600 - Caches the page on the edge for 1 hour, while browsers revalidate on every request.
public, max-age=31536000, immutable - For fingerprinted assets in /_astro/.
private, no-store - For the admin panel, API, previews, and personalized responses.

For example, in an Astro page:

---
// src/pages/posts/[slug].astro
Astro.response.headers.set("Cache-Control", "public, max-age=0, s-maxage=3600");
---

Purge the edge cache on publish

Sevalla purges both caches after every deploy, but content changes in EmDash don’t trigger a deploy. To show new content right away, call the Sevalla API to clear the edge cache when an editor publishes, updates, or deletes content:

// src/lib/purge.ts
export async function purgeEdgeCache() {
  const response = await fetch(
    `https://api.sevalla.com/v3/applications/${process.env.SEVALLA_APP_ID}/purge-cache`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.SEVALLA_API_KEY}` },
    }
  );

  if (!response.ok) {
    console.error(`Edge cache purge failed: HTTP ${response.status}`);
  }
}

Create the API key with only the permissions needed to purge the application’s cache. Sevalla purges the whole application cache at once, so group bursts of edits into a single purge. The Sevalla template implements this as an Astro cache provider and an EmDash plugin. It purges the cache after every content change, including scheduled posts that go live without a request, and never caches a response for a request that carries a session cookie. See src/sevalla/edge-cache.ts and src/sevalla/purge.ts.

Health checks

Ensure your application remains available during deployments by implementing health checks:

Always implement health checks for production applications.
Keep checks lightweight; responses should complete in under 1 second.
Use a basic check for the liveness probe and a check that also verifies PostgreSQL for the readiness probe.
Return 503 only for critical failures that require pod restarts.
Never cache health check responses.

Health check with database verification

// src/pages/healthz.ts
import type { APIRoute } from "astro";
import pg from "pg";

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 1 });

export const GET: APIRoute = async ({ url }) => {
  const headers = { "Cache-Control": "no-store", "Content-Type": "application/json" };

  if (!url.searchParams.has("db")) {
    return new Response(JSON.stringify({ status: "ok" }), { headers });
  }

  try {
    await pool.query("SELECT 1");
    return new Response(JSON.stringify({ status: "ok", db: "ok" }), { headers });
  } catch {
    return new Response(JSON.stringify({ status: "error", db: "unreachable" }), {
      status: 503,
      headers,
    });
  }
};

Use /healthz for the liveness probe and /healthz?db=1 for the readiness probe.

Scaling

EmDash can run on multiple instances when all state lives outside the container. Before you increase the instance count or enable autoscaling, make sure that:

Content is stored in PostgreSQL and media in Object Storage.
Astro sessions are stored in a shared store. On Node.js, Astro stores sessions on the local filesystem by default, so editors are signed out on every deploy and when requests reach a different instance.
At least one instance is always running, because EmDash’s scheduler for scheduled publishing and plugin tasks runs inside the Node.js process.

Troubleshooting

Build fails with `Rollup failed to resolve import "@aws-sdk/client-s3"`

EmDash’s s3() adapter doesn’t bundle the AWS SDK. Install @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner as dependencies.

Media uploads fail in the admin panel

Check that the bucket’s CORS policy allows your application’s origin with PUT, GET, and HEAD, and the content-type header.
Add every custom domain you use for the admin panel to the CORS policy.
Set AWS_REQUEST_CHECKSUM_CALCULATION and AWS_RESPONSE_CHECKSUM_VALIDATION to WHEN_REQUIRED.

Passkeys don’t work after adding a custom domain

Passkeys are tied to the origin they were registered on. Update EMDASH_SITE_URL to the new domain, redeploy, and register a new passkey on the new domain before removing the old one.

Search returns no results

EmDash’s built-in search uses SQLite full-text search and returns no results on PostgreSQL. Use PostgreSQL full-text search instead, as the Sevalla template does in src/sevalla/search.ts.

Migrations fail with `must be owner of table`

EmDash needs to own its tables. Connect with the same database user that created them, and don’t switch to a different user in DATABASE_URL.

Hey 👋

Quick starts

Projects

Applications

Databases

Object storage

Load balancers

Static sites

Sevalla API

Billing

Company settings

Integration

User settings

Support

Service information

Sevalla template

Application Hosting

Required adjustments

Configuration

Environment variables

Object Storage

Containerization

Dockerfile

Nixpacks

Buildpacks

Database migrations

CDN

Edge caching

`Cache-Control`

Purge the edge cache on publish

Health checks

Scaling

Troubleshooting

Build fails with `Rollup failed to resolve import "@aws-sdk/client-s3"`

Media uploads fail in the admin panel

Passkeys don’t work after adding a custom domain

Search returns no results

Migrations fail with `must be owner of table`

​Sevalla template

​Application Hosting

​Required adjustments

​Configuration

​Environment variables

​Object Storage

​Containerization

​Dockerfile

​Nixpacks

​Buildpacks

​Database migrations

​CDN

​Edge caching

​Cache-Control

​Purge the edge cache on publish

​Health checks

​Scaling

​Troubleshooting

​Build fails with Rollup failed to resolve import "@aws-sdk/client-s3"

​Media uploads fail in the admin panel

​Passkeys don’t work after adding a custom domain

​Search returns no results

​Migrations fail with must be owner of table

Sevalla template

Application Hosting

Required adjustments

Configuration

Environment variables

Object Storage

Containerization

Dockerfile

Nixpacks

Buildpacks

Database migrations

CDN

Edge caching

`Cache-Control`

Purge the edge cache on publish

Health checks

Scaling

Troubleshooting

Build fails with `Rollup failed to resolve import "@aws-sdk/client-s3"`

Media uploads fail in the admin panel

Passkeys don’t work after adding a custom domain

Search returns no results

Migrations fail with `must be owner of table`