Self-hosting with Docker

Think of docker compose up as the one command that starts your whole backend: the sync engine, the HTTP API, any httpAction webhooks, and the dashboard, all in one container.

This is the baseline way to self-host helipod. A generic helipod:latest image runs helipod serve, your app's helipod/ folder is mounted in, and its SQLite database sits on a named volume so data survives restarts.

This page covers serve itself (what it hardens versus dev, and every flag and environment variable it reads), the shipped Docker setup and why its two non-obvious fixes exist, the immutable-image alternative, and what's deliberately left to a reverse proxy.

helipod serve: the production entrypoint

helipod serve is helipod dev minus the file watcher and codegen-write, plus production hardening.

Both share one boot core, bootProject() (packages/cli/src/boot.ts). It loads the project, composes components, opens the store, and builds the EmbeddedRuntime and AdminApi with byte-identical options either way: routes, drivers, boot steps, context providers, table numbers.

Nothing about how your functions run (schedulers, workflows, actions, httpActions, triggers) is dev-only or serve-only. Only the process-level behavior around that shared core differs:

Fail-fast checks, before anything binds

serveCommand validates two things up front, before opening the store or binding a port, and exits 1 with a one-line, actionable message on either:

1. HELIPOD_ADMIN_KEY must be set and non-blank. There is no default and no fallback. A trimmed-empty value is treated as unset.

   ✗ HELIPOD_ADMIN_KEY is required for `serve`: set it to a strong secret.

2. <dir>/_generated/server.ts must already exist. serve never runs codegen. That step belongs in your build/CI pipeline, not on every production boot. Generate it and commit it before deploying:

   helipod codegen --dir helipod

   ✗ helipod/_generated not found: run `helipod codegen --dir helipod` and commit _generated/ before deploying.

Binding and graceful shutdown

serve binds 0.0.0.0 by default, versus dev's loopback-only bind. It's meant to be reached from outside the container or host, and a reverse proxy or the Docker port mapping is what actually exposes it publicly.

SIGTERM and SIGINT both trigger the same idempotent shutdown sequence. It's safe to receive twice: a second signal while shutting down is a no-op.

1. Stop the fleet node, if running one (--fleet).
2. server.close(): stops every registered driver (scheduler, triggers, reapers, wake heartbeats) and closes listening sockets.
3. Release any object-storage lease (--object-store), best-effort, bounded to 2 seconds so an unreachable bucket can't hang shutdown past a container's grace period.
4. store.close(): closes the database connection or file handle.
5. process.exit(0).

This is what makes docker compose down / docker stop (which send SIGTERM, then SIGKILL after a grace period) a clean stop rather than a killed process. The store is closed before exit, not left in a torn state.

What it serves

One process answers everything on one origin: the sync WebSocket, /api/run and /api/action HTTP endpoints, httpAction routes from your app's http.ts, the always-on /api/storage/* file-serving routes, any component-contributed routes (for example @helipod/auth's OAuth callbacks), and, unless disabled, the dashboard SPA at /_dashboard.

The dashboard is served key-less

Unlike dev, which embeds its ephemeral admin key directly into the dashboard's HTML (safe, because that key only ever exists on loopback), serve calls loadDashboard(undefined). The admin key is never baked into the HTML the browser receives.

Instead, the dashboard SPA prompts you for the key on load. You paste in whatever you set HELIPOD_ADMIN_KEY to, and it's used from then on to authenticate /_admin calls.

This matters because a 0.0.0.0-bound serve is reachable by anyone who can reach the port. Embedding a persistent secret in served HTML would leak it to any visitor, not just the operator.

Flags and environment variables

Every serve option can be set as a CLI flag or an environment variable. Where both exist, the flag wins.

serve reads env vars once at startup. There's no live reconfiguration, so restart to change any of these.

HELIPOD_ADMIN_KEY is required and has no flag equivalent. That's deliberate: a secret belongs in the environment, not in a process argument list visible via ps.

Docker: the baseline self-host path

helipod codegen --dir helipod

HELIPOD_ADMIN_KEY=$(openssl rand -hex 32)

docker compose up

services:
  helipod:
    build:
      context: .
      target: runner
    image: helipod:latest
    ports:
      - "3000:3000"
    environment:
      HELIPOD_ADMIN_KEY: ${HELIPOD_ADMIN_KEY:?set HELIPOD_ADMIN_KEY in a .env file}
      HELIPOD_DATA_DIR: /data
    volumes:
      - ./helipod:/app/helipod:ro
      - helipod-data:/data
    command: ["serve", "--dir", "/app/helipod", "--data", "/data/db.sqlite"]
    restart: unless-stopped

volumes:
  helipod-data:

# 1) Bring it up
docker compose up -d

# 2) Health check
curl -f localhost:3000/api/health
# {"status":"ok","functions":N,"tables":N}

# 3) Open the dashboard, paste the admin key from .env
open http://localhost:3000/_dashboard

# 4) Write some data via the dashboard or a mutation, then restart
docker compose down
docker compose up -d

# 5) Confirm the data written in step 4 is still there

Going deeper

RUN <<'EOF'
bun -e '
  const fs = require("fs");
  fs.mkdirSync("node_modules/@helipod", { recursive: true });
  for (const base of ["packages", "components"]) {
    if (!fs.existsSync(base)) continue;
    for (const d of fs.readdirSync(base)) {
      const pj = base + "/" + d + "/package.json";
      if (!fs.existsSync(pj)) continue;
      const name = JSON.parse(fs.readFileSync(pj, "utf8")).name;
      if (!name || !name.startsWith("@helipod/")) continue;
      try { fs.symlinkSync("/app/" + base + "/" + d, "node_modules/" + name); } catch {}
    }
  }
'
EOF

RUN mkdir -p /data /app/.helipod-deploy && chown bun:bun /data /app /app/.helipod-deploy
USER bun

FROM helipod:latest
COPY ./helipod /app/helipod
# ENTRYPOINT/CMD are inherited from helipod:latest:
#   serve --dir /app/helipod --data /data/db.sqlite

docker build -t myapp:latest .
docker run -p 3000:3000 -e HELIPOD_ADMIN_KEY=... -v helipod-data:/data myapp:latest

Using Postgres

SQLite is the zero-config default. Point serve at Postgres instead with --database-url or HELIPOD_DATABASE_URL. No other change to the compose file's shape is required beyond swapping the SQLite volume for the connection string.

Postgres is a single-node durability upgrade (a managed database instead of a SQLite file on a volume) via a pg_advisory_lock single-writer guard, not multi-node scale-out. It needs no app-schema migrations as schema.ts evolves. See Postgres for the full compose example, the single-writer constraint, and its known limitations.

Other platforms (Railway, Fly.io)

Any platform that can run a long-lived process with WebSocket support and a persistent disk can host helipod serve; Docker is the baseline, not a requirement. The checklist is always the same: set HELIPOD_ADMIN_KEY as a platform secret (never in a config file), mount a persistent volume for the data directory, and point health checks at GET /api/health.

[build]
builder = "nixpacks"

[deploy]
startCommand = "helipod serve --dir ./helipod --data /app/data/db.sqlite"
healthcheckPath = "/api/health"
healthcheckTimeout = 30

[[mounts]]
source = "data"
destination = "/app/data"

app = "my-helipod-app"
primary_region = "iad"

[mounts]
source = "data"
destination = "/app/data"

[http_service]
internal_port = 3000
force_https = true

[[http_service.checks]]
interval = "10s"
timeout = "2s"
path = "/api/health"

A managed Postgres on either platform works through the same HELIPOD_DATABASE_URL as anywhere else. Both platforms also have an automated push path: helipod deploy --target railway and --target fly shell out to the platform's own CLI (railway up, fly deploy) after refreshing codegen. See Deploy and build.

Reverse proxy / TLS

Related

• Postgres: swap the SQLite volume for a Postgres database, still single-node.
• Deploy and build: helipod deploy for live hot-swap onto a running serve (no restart, --allow-deploy opt-in), and helipod build for a single self-contained binary instead of a runtime-based image.
• Scaling: when one serve process isn't enough, the multi-node fleet story (--fleet) built on the same Postgres backend.
• Cloudflare: an alternative host if you specifically want Cloudflare's edge/scale-to-zero economics.