This guide explains how the orgtable container infrastructure is built and why each decision is where it is. It is meant for contributors who want to understand or modify the image and the orchestration. The infrastructure is in place and verified working end to end.
The stack is made of:
| Piece | File | Role |
|---|---|---|
| App image | Dockerfile |
Multi-stage build that produces the Next.js production image. |
| Orchestration | docker-compose.yml |
Starts PostgreSQL + the app, with an internal network and healthchecks. |
| Container start-up | docker-entrypoint.sh |
Applies the Prisma migrations and starts the server. |
| Build context | .dockerignore |
Excludes what must not end up in the image (secrets included). |
| Next output | next.config.ts |
output: "standalone" packages a minimal Node server. |
To install and run it on a real server, see installation.md. For the data schema and migrations, see database.md.
The Dockerfile has three stages: deps, builder and runner. The idea is to build with every tool available but ship only what is essential to production.
FROM base AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
RUN pnpm install --frozen-lockfileIt runs pnpm install --frozen-lockfile (pnpm comes from Corepack, in a base stage) on node:22-alpine. Using Alpine here is deliberate, not cosmetic.
Alpine Linux uses musl libc (not glibc). Prisma downloads native engines during installation, one of which is the schema engine used by migrate deploy. Installing inside Alpine downloads that binary for the linux-musl platform, which is exactly what the final container (also Alpine) runs. If the dependencies were installed on a glibc-based image (e.g. Debian node:22), the engine would be built for glibc and would fail in the Alpine runner. Keeping Alpine end to end guarantees that the engine matches the system it runs on.
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV DATABASE_URL="postgresql://build:build@localhost:5432/build"
RUN pnpm exec prisma generate
RUN pnpm buildIt reuses the node_modules installed in deps, copies the code and does two things: generates the Prisma Client and builds the app.
The key detail is the dummy DATABASE_URL defined before prisma generate:
- Prisma 7 must resolve
DATABASE_URLwhen loadingprisma.config.ts. If the variable is missing, loading the configuration throws andprisma generate/pnpm builddo not even start. - However, neither
generatenor the build actually connects to the database.generateonly produces the client (WASM query engine, no binary), and the app pages are dynamic (they depend on the session), so they do not query the database during the build. The URL only needs to exist and be syntactically valid; no connection tolocalhost:5432is ever opened.
After this, pnpm build produces .next/standalone thanks to output: "standalone" (see next.config.ts).
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0
RUN apk add --no-cache openssl
RUN addgroup -g 1001 nodejs && adduser -u 1001 -G nodejs -S nextjs
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
COPY --from=builder /app/node_modules ./node_modules
# ... prisma/, prisma.config.ts, package.json
COPY --chmod=755 docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN mkdir -p .next/cache && chown nextjs:nodejs .next/cache
USER nextjs
EXPOSE 3000
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["node", "server.js"]Key points of the runner:
node:22-alpineagain, so the Prisma schema engine (downloaded indepsforlinux-musl) is compatible with the runtime system.apk add --no-cache openssl: the Prisma schema engine needsopensslto runmigrate deploy. Alpine does not ship it by default, so it is installed explicitly.- Unprivileged
nextjsuser (non-root): thenodejsgroup andnextjsuser are created and the image switches to that user withUSER nextjs. The app never runs as root. - The code is read-only for the app:
/appstays owned byroot, so the process cannot rewriteserver.js,.nextornode_modules. Only.next/cache(Next cache) and/data/uploads(attachments) are writable. There is nochown -R /app: besides making the code writable, it would duplicatenode_modulesin a new layer of hundreds of MB. - The production artefacts are copied:
.next/standalone(the minimal Node server),.next/static,public, plusprisma/,prisma.config.tsandpackage.json(needed for the migrations).
This is the least obvious part. The runner copies all of node_modules from the builder, not just prisma and @prisma:
COPY --from=builder /app/node_modules ./node_modulesThe reason is the Prisma CLI. At start-up the entrypoint runs prisma migrate deploy, and that CLI depends on hoisted transitive dependencies, for example effect, which @prisma/config uses. The dependency tracing of output: "standalone" only includes what the app itself imports, not what the Prisma CLI imports. If only prisma/@prisma were copied, the CLI would be missing pieces such as effect and migrate deploy would fail. Copying the whole tree guarantees that both the app and the CLI have everything they need.
Possible improvement. Copying the whole
node_modulesinflates the image. Aprod-depsstage could runpnpm install --prod --frozen-lockfileand copy only that tree into therunner, reducing the final size.
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["node", "server.js"]The ENTRYPOINT runs the start-up script (migrations), which finally execs the CMD that starts the standalone server (node server.js).
#!/bin/sh
set -e
echo "[orgtable] Applying database migrations..."
node node_modules/prisma/build/index.js migrate deploy
echo "[orgtable] Starting the server..."
exec "$@"Every time the app container starts:
- It applies pending migrations with
prisma migrate deploy. This is idempotent: it only runs the migrations that have not been applied yet, comparing against the history recorded in the database. Starting the container many times never reapplies existing migrations. - The CLI is invoked by its direct path (
node node_modules/prisma/build/index.js) instead ofnpx, so it does not depend on the.binsymlinks (which may be missing depending on hownode_moduleswas copied or hoisted). exec "$@"replaces the script process with theCMD(node server.js), so the Next server becomes PID 1 and receives the container signals correctly.
More on the schema and the migration flow in database.md.
It defines two services (postgres and app), two volumes (pgdata for the database and uploads for attachments) and an internal bridge network (orgtable).
postgres:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 10
networks:
- orgtablepostgres:17-alpinewith persistence in thepgdatavolume (data survives container re-creation).- Healthcheck with
pg_isready: marks the servicehealthyonly when the database accepts connections. This is what letsappwait correctly (see below). - It exposes no port to the host. PostgreSQL is only reachable from the internal
orgtablenetwork, never from outside the host. This is a security decision: the database must not be published on the host machine; only the app needs to talk to it, and it does so over the Docker network.
app:
build:
context: .
dockerfile: Dockerfile
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
environment:
DATABASE_URL: ${DATABASE_URL}
SESSION_SECRET: ${SESSION_SECRET}
NODE_ENV: production
ORGTABLE_UPLOAD_DIR: ${ORGTABLE_UPLOAD_DIR:-/data/uploads}
ORGTABLE_REALTIME_PG_NOTIFY: ${ORGTABLE_REALTIME_PG_NOTIFY:-0}
CRON_SECRET: ${CRON_SECRET:-}
TRUSTED_PROXY_HOPS: ${TRUSTED_PROXY_HOPS:-0}
ORGTABLE_TIMEZONE: ${ORGTABLE_TIMEZONE:-Atlantic/Canary}
ORGTABLE_AUDIT_RETENTION_DAYS: ${ORGTABLE_AUDIT_RETENTION_DAYS:-}
ORGTABLE_SOURCE_URL: ${ORGTABLE_SOURCE_URL:-}
ORGTABLE_LANDING: ${ORGTABLE_LANDING:-}
ORGTABLE_INSTALL_URL: ${ORGTABLE_INSTALL_URL:-}
ORGTABLE_SMTP_URL: ${ORGTABLE_SMTP_URL:-}
ORGTABLE_MAIL_FROM: ${ORGTABLE_MAIL_FROM:-}
ORGTABLE_PUBLIC_URL: ${ORGTABLE_PUBLIC_URL:-}
volumes:
- uploads:/data/uploads
ports:
- "${APP_PORT:-3000}:3000"
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:3000/api/health || exit 1"]
interval: 10s
timeout: 5s
retries: 5
start_period: 20s
networks:
- orgtable- Local build from the repository
Dockerfile(context: .). The image is built on the user's server, not pulled from a registry. depends_onwithcondition: service_healthy: the app does not start until PostgreSQL ishealthy. So when the entrypoint runsmigrate deploy, the database is already accepting connections.- It only receives the variables under
environment:, not the whole.env. If a new variable is not added here, the app does not see it inside the container (CI checks this for the optional ones). What each one does: variables table ininstallation.md. uploadsvolume mounted at/data/uploads: attachments survive container re-creation.- Publishes the port
${APP_PORT:-3000}:3000(configurable withAPP_PORT,3000by default, on every interface). WithAPP_PORT=127.0.0.1:3000it is only published on localhost, which is what you want behind a reverse proxy (self-hosting.md). It is the only service exposed to the host. - Healthcheck with
wgetagainsthttp://127.0.0.1:3000/api/health.
This detail used to be broken and was fixed: 127.0.0.1 is used explicitly, not localhost.
Inside the container, localhost resolves to the IPv6 address ::1, while the Next standalone server listens on IPv4 0.0.0.0 (set with HOSTNAME=0.0.0.0 in the Dockerfile). With localhost, wget tried to connect over IPv6 to a server that was not listening there, and the healthcheck returned "Connection refused", marking the container unhealthy even though the app worked. Forcing 127.0.0.1 (IPv4) points the check exactly where the server listens.
start_period: 20s: gives the initial start-up some slack. The container first applies migrations and then starts the server, so for the first few seconds the endpoint does not answer yet;start_periodkeeps those early failures from counting asunhealthy.
The stack does not include Redis. This is a conscious decision, documented in docs/decisions/0004-no-redis-mvp.md.
The .dockerignore shrinks the build context and, above all, keeps secrets from leaking:
| Pattern | Reason |
|---|---|
node_modules |
Reinstalled inside the image (pnpm install --frozen-lockfile); the host copy is not sent. |
.next |
Build artefact, regenerated inside the container. |
.git, .gitignore |
History and metadata not needed in the image. |
.env, .env.* |
CRITICAL: secrets must never end up in the image. |
!.env.example |
Exception: the example without secrets is kept. |
docs, *.md, .claude, .agents, skills-lock.json |
Documentation and development tooling, irrelevant at runtime. |
backups, **/*.sql.gz, **/*.tar.gz, uploads, data, **/*.pem |
Backups (with personal data), development attachments and keys: COPY . . would put them in the builder and its cache. |
coverage, test, scripts, install.sh |
Tests and scripts that run on the host; the image does not use them. |
npm-debug.log*, *.tsbuildinfo |
Logs and temporary files. |
The most important point is the .env* files: credentials (DATABASE_URL, SESSION_SECRET, etc.) are injected through the environment at runtime (via docker-compose.yml / the host .env), never baked into the image. The only exception is .env.example, a template with no real values. This follows docs/decisions/0003-db-creds-in-env.md.
You need Docker and Docker Compose, and a .env file with the required variables (install.sh generates it; see installation.md).
Build the images:
docker compose buildStart the stack in the background:
docker compose up -dCheck the status and the logs:
docker compose ps
docker compose logs -f appWhen both services show as healthy, the app is available at http://localhost:${APP_PORT:-3000}.
Stop the stack:
docker compose down(docker compose down -v would also delete the pgdata and uploads volumes and, with them, all the data and all the attachments.)
The start-up order is coordinated by the Postgres healthcheck and the app entrypoint:
postgresstarts and, oncepg_isreadyanswers, is markedhealthy.appstarts (it was waiting ondepends_on: condition: service_healthy). ItsENTRYPOINTrunsdocker-entrypoint.sh.- The entrypoint applies the migrations with
prisma migrate deploy(idempotent: only the missing ones). - The server starts via
exec node server.js, listening on IPv40.0.0.0:3000. - The healthcheck passes:
wgettohttp://127.0.0.1:3000/api/healthanswers andappis markedhealthy.start_periodcovers the time for migrations + start-up.
postgres (pg_isready) ──healthy──▶ app entrypoint (migrate deploy) ──▶ node server.js ──▶ /api/health OK ──▶ app healthy
Summary: a multi-stage Alpine build packages the Next standalone server with the whole node_modules, so the Prisma CLI can migrate the database at start-up, while Compose coordinates Postgres (private, with a healthcheck) and the app (migrates and starts), injecting secrets only at runtime.