Deploy to Railway — Dockerfile, Volume, production

Code

The deploy files and the Railway CLI

Four files as tabs — the container, the ignore list, the Railway config, and the env template. Dockerfile → .dockerignore → railway.json → .env.example.

1. Dockerfile (new) — the multi-stage build. Stage one (golang:1.26) downloads modules on their own cached layer, copies the source, and go builds a static binary (CGO_ENABLED=0, -trimpath -ldflags="-s -w" for a smaller, reproducible result). Stage two is distroless/static-debian12 — it carries CA certificates (needed for the Resend HTTPS call) and nothing else. The final image is just COPY --from=build of the binary. templ/sqlc output is committed, so the build is a plain go build with no code-gen step.

2. .dockerignore (new) — keeps the build context small and secrets out of the image: .git/, uploads/, *.exe, .env, *.md. Never ship your local .env or your local uploads into an image.

3. railway.json (new) — selects the DOCKERFILE builder, points at Dockerfile, and configures the deploy: /healthz healthcheck, restart on failure. Railway reads this on every deploy.

4. .env.example (new) — the documented surface of every variable, committed so a new developer copies it to .env. It spells out which vars are required in prod (SESSION_SECRET, BASE_URL) and flags the ephemeral-filesystem note on UPLOAD_DIR — the decision this lesson resolves.

Deploy it (Railway CLI — a free account is enough):

railway login
railway init --name signflow
railway add --database postgres          # provides DATABASE_URL

# Deploy the service with prod config. SESSION_SECRET is generated on the spot.
railway add --service signflow \
  --variables APP_ENV=prod \
  --variables 'DATABASE_URL=${{Postgres.DATABASE_URL}}' \
  --variables UPLOAD_DIR=/data/uploads \
  --variables "SESSION_SECRET=$(openssl rand -base64 32)"

railway up                                # build the Dockerfile and deploy
railway domain                            # get your public URL

Then, in the Railway dashboard, add a Volume to the service mounted at /data (so UPLOAD_DIR=/data/uploads lands on persistent disk), and set BASE_URL to the domain Railway gave you (it goes into email links). Redeploy.

On boot the binary runs its migrations against the Postgres addon and starts serving. Watch the deploy logs:

INFO starting signflow env=prod port=8080 base_url=https://signflow-....up.railway.app
INFO goose msg="OK    00001_users.sql"
...
INFO file storage: local disk dir=/data/uploads
INFO listening addr=:8080

/healthz goes green and the URL is live.

Dockerfile CREATE

Create this file in ./

# Multi-stage build. The final image is a single static binary on distroless —
# migrations and static assets are embedded (//go:embed), so nothing else ships.

# ---- build ----
FROM golang:1.26 AS build
WORKDIR /src

# Cache module downloads.
COPY go.mod go.sum ./
RUN go mod download

# Build. templ/sqlc output is committed, so this is a plain `go build`.
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/signflow ./cmd/signflow

# ---- runtime ----
# distroless/static ships CA certificates (needed for the Resend HTTPS call) and
# runs as root, so it can write to the mounted Railway Volume.
FROM gcr.io/distroless/static-debian12
COPY --from=build /out/signflow /signflow

# Railway overrides PORT at runtime; this is just the default/dev value.
ENV PORT=8080
EXPOSE 8080

ENTRYPOINT ["/signflow"]

railway.json CREATE

Create this file in ./

{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "DOCKERFILE",
    "dockerfilePath": "Dockerfile"
  },
  "deploy": {
    "healthcheckPath": "/healthz",
    "healthcheckTimeout": 100,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}

.env.example CREATE

Create this file in ./

# Copy to .env for local development. `go run` loads it automatically.

# Postgres connection string (pgx/libpq format).
DATABASE_URL=postgres://postgres@localhost:5432/signflow?sslmode=disable

# HTTP port. Railway sets this for you in production.
PORT=8080

# "dev" or "prod". prod requires SESSION_SECRET and BASE_URL and sets Secure cookies.
APP_ENV=dev

# Public origin used to build links in emails. Defaults to http://localhost:PORT in dev.
# BASE_URL=https://signflow.up.railway.app

# Secret used to authenticate session cookies. REQUIRED in prod.
# Generate: openssl rand -base64 32
# SESSION_SECRET=

# Where uploaded document files are stored (local disk in dev).
# NOTE: Railway's filesystem is ephemeral — in prod point this at a mounted
# Railway Volume, or swap storage.Store for object storage. See README.
UPLOAD_DIR=uploads

# Email provider. "console" (default in dev) prints links to the terminal.
# Set to "resend" and provide RESEND_API_KEY to send real email in prod.
EMAIL_SENDER=console
# RESEND_API_KEY=
# EMAIL_FROM=SignFlow <no-reply@yourdomain.com>