Deployment

Docker

The repository ships a multi-stage Dockerfile that builds a static binary and runs it as a non-root user on Alpine.

docker build -t mellow .
docker run --env-file .env -p 9420:9420 mellow

The image has no shell entrypoint beyond the binary; pass configuration via --env-file or -e.

Railpack / Railway

railpack.json defines a Go build and start command:

{
  "provider": "go",
  "steps": { "build": { "commands": ["go build -trimpath -ldflags \"-s -w -X main.version=${RAILPACK_GIT_SHA:-dev}\" -o bin/mellow ./cmd/mellow"] } },
  "deploy": { "startCommand": "./bin/mellow" }
}

On Railway (or any Railpack host):

1. Create a project and add a PostgreSQL database.
2. Set the environment variables (the reference lists them). Point DATABASE_URL at the database plugin, keeping sslmode=require.
3. Deploy. Migrations run automatically on boot.
4. Expose PORT if you want the HTTP API reachable; otherwise leave it internal.

Any host

Because Mellow is one binary, any process manager works:

# /etc/systemd/system/mellow.service
[Service]
EnvironmentFile=/opt/mellow/.env
ExecStart=/opt/mellow/mellow
Restart=on-failure
User=mellow

Version stamping

Builds set the version via -ldflags "-X main.version=...". /version and the startup update check compare this against the latest GitHub release, so set it to your tag or commit SHA.

Deploy pipeline tip

Run migrations as a separate step before rolling out the new binary:

MELLOW_MIGRATE_ONLY=1 ./mellow

HTTP API

The API serves:

• GET /healthz - health check (unauthenticated)
• GET /v1/stats - aggregate counts
• GET /v1/status - live bot and per-shard status (unauthenticated)
• GET /v1/testimonials - approved testimonials
• POST /v1/chat - chat completion (Bearer API_TOKEN)
• POST /v1/feedback - submit feedback (Bearer API_TOKEN)
• GET /openapi.json and GET /docs - the OpenAPI spec and a Scalar reference

Put it behind a TLS-terminating reverse proxy. See the