Docker
Containers are the most portable way to run the Node build of a Ghuri project: the same image
runs on Fly.io, Railway, Render, ECS, Kubernetes or a single VPS with docker compose. Read
Node and Postgres on a VPS first; this page assumes the
environment-driven settings and the build:node script described there.
Dockerfile
Section titled “Dockerfile”A three-stage build: install all dependencies and compile, install production dependencies only, then copy both into a slim runtime image.
# syntax=docker/dockerfile:1
FROM node:22-slim AS buildWORKDIR /appCOPY package.json package-lock.json ./RUN npm ciCOPY . .RUN npm run build:node
FROM node:22-slim AS depsWORKDIR /appCOPY package.json package-lock.json ./RUN npm ci --omit=dev
FROM node:22-slim AS runtimeWORKDIR /appENV NODE_ENV=production PORT=8000COPY --from=deps /app/node_modules ./node_modulesCOPY --from=build /app/dist ./dist# The ghuri CLI loads TypeScript sources, so keep them for `migrate` and friends.COPY package.json tsconfig.json ./COPY src ./srcUSER nodeEXPOSE 8000CMD ["node", "dist/server.js"]Three details matter:
src/is copied into the runtime image. The server runs the compileddist/server.js, butghuri migrateand other management commands load your settings and migrations from TypeScript with jiti. Withoutsrc/you cannot run them inside the container.@ghuri/climust be a production dependency for the same reason. The generatedpackage.jsonlists it underdevDependencies, so move it (npm install @ghuri/cli@nextmoves it todependencies).jitiis already a dependency. If you would rather keep the image minimal, run migrations from CI or a separate “release” image built from thebuildstage.wrangler.jsoncis not copied. Without it the CLI buildsenvfromprocess.envalone, which is what you want in a container.
If you skip the build step, drop the build stage and the dist copy and start the server
the way npm start does: CMD ["node", "--import", "jiti/register", "src/server.ts"].
Add a .dockerignore so local state does not end up in the image:
node_modulesdist.wrangler.dev.vars.env.gitmedia*.sqlite3docker compose for local production-like runs
Section titled “docker compose for local production-like runs”This compose file runs the app with Postgres and MinIO as an S3-compatible store, which is close to a typical self-hosted production setup.
services: db: image: postgres:17 environment: POSTGRES_DB: mysite POSTGRES_USER: mysite POSTGRES_PASSWORD: mysite volumes: [pgdata:/var/lib/postgresql/data] healthcheck: test: ["CMD-SHELL", "pg_isready -U mysite"] interval: 2s retries: 30
minio: image: minio/minio command: server /data --console-address ":9001" environment: MINIO_ROOT_USER: minio MINIO_ROOT_PASSWORD: minio-secret ports: ["9000:9000", "9001:9001"] volumes: [media:/data]
migrate: build: . command: ["npx", "ghuri", "migrate"] env_file: .env.docker depends_on: db: { condition: service_healthy }
web: build: . env_file: .env.docker ports: ["8000:8000"] depends_on: migrate: { condition: service_completed_successfully } minio: { condition: service_started }
volumes: pgdata: media:SECRET_KEY=dev-only-not-secretDEBUG=falseALLOWED_HOSTS=localhost,127.0.0.1DATABASE_URL=postgres://mysite:mysite@db:5432/mysiteS3_ENDPOINT=http://minio:9000S3_BUCKET=mysite-mediaS3_ACCESS_KEY_ID=minioS3_SECRET_ACCESS_KEY=minio-secretS3_REGION=us-east-1MEDIA_PUBLIC_URL=http://localhost:9000/mysite-mediaCreate the bucket once (in the MinIO console at http://localhost:9001, or with mc mb), then:
docker compose up --builddocker compose run --rm web npx ghuri createsuperuserRunning migrations on release
Section titled “Running migrations on release”Never run ghuri migrate from the web container’s CMD. When several replicas start at once
they race to apply the same migration. Run it exactly once per release instead:
| Platform | Where migrations go |
|---|---|
| docker compose | a one-shot migrate service the web service depends on (above) |
| Fly.io | [deploy] release_command = "npx ghuri migrate" in fly.toml |
| Render | “Pre-Deploy Command”: npx ghuri migrate |
| Kubernetes | a Job (or Helm pre-upgrade hook) running npx ghuri migrate |
| CI | a step before the rollout, with the production DATABASE_URL |
As on any platform, ship backwards-compatible migrations: add columns as nullable or with a default first, deploy, and only then remove what the old code needed.
Health checks
Section titled “Health checks”Add a cheap view and point your orchestrator at it:
path('healthz/', (c) => c.text('ok'), { name: 'healthz' }),If you want the check to fail when the database is unreachable, run a trivial query:
import { connections } from '@ghuri/orm'
path('healthz/', async (c) => { const conn = await connections.get() await conn.execute('SELECT 1') return c.text('ok')}),