Production Deployment Guide¶

This guide covers everything required to run Farm in a production environment. All default values in the codebase are designed for local development and must be overridden before going live.

Pre-deployment Checklist¶

• Generate a strong JWT_SECRET (minimum 32 characters)
• Point DATABASE_* variables to a managed PostgreSQL instance
• Set DATABASE_SYNC=false and run migrations manually
• Set NODE_ENV=production
• Restrict ALLOWED_ORIGINS to your domain
• Change SWAGGER_USER and SWAGGER_PASSWORD
• Configure Redis (REDIS_HOST) for queues and real-time notifications
• Set NEXT_PUBLIC_API_URL on the frontend to the public API URL
• Run GET /api/health after deploy and confirm all indicators are up

Environment Variables¶

API (apps/api/.env or container environment)¶

Required¶

Generate a secure JWT secret:

openssl rand -hex 32

Recommended¶

Redis (required for pipelines and real-time notifications)¶

Without Redis, pipeline execution queues and WebSocket notifications are disabled.

Email (optional)¶

Observability (optional but recommended)¶

OAuth Social Login (optional)¶

Leave all six empty to disable social login. See the OAuth Social Login section for instructions on creating the OAuth Apps.

CI/CD Integrations (optional)¶

Credentials for ArgoCD, CircleCI, Jenkins, and Travis CI are stored per-organization in the database (encrypted with AES-256-GCM) and managed through the Integration Settings page — no env vars required.

Kubernetes and Helm (optional)¶

Plugin System (optional)¶

Frontend (apps/web/.env.local or container environment)¶

Database Migrations¶

Never use DATABASE_SYNC=true in production. Schema changes must be applied through migrations:

# Apply all pending migrations
cd apps/api
npm run migration:run

# Revert the last migration if something goes wrong
npm run migration:revert

# Generate a new migration after entity changes (development only)
npm run migration:generate

Migration files live in apps/api/src/migrations/. Always commit migrations alongside the entity changes that require them.

Docker Compose¶

The repository includes a production-ready Docker Compose setup:

# Start API + PostgreSQL + Redis
docker compose up -d

# Start full stack including Grafana, Prometheus, and Tempo
docker compose -f docker-compose.yml -f docker-compose.observability.yml up -d

For production, override the default credentials by creating a .env file at the repository root or by passing environment variables directly to your container runtime.

Example .env for Docker Compose¶

NODE_ENV=production
JWT_SECRET=<openssl rand -hex 32 output>
DATABASE_PASSWORD=strong_db_password
DATABASE_POOL_SIZE=20
ALLOWED_ORIGINS=https://seudominio.com
SWAGGER_USER=ops
SWAGGER_PASSWORD=strong_swagger_password
REDIS_HOST=redis
NEXT_PUBLIC_API_URL=https://api.seudominio.com/api
API_INTERNAL_URL=http://api:3000/api
NEXT_PUBLIC_WS_URL=https://api.seudominio.com

Kubernetes¶

Farm ships Helm charts under charts/farm/. See the Helm Integration guide for full deployment instructions.

helm upgrade --install farm ./charts/farm \
  --set api.env.NODE_ENV=production \
  --set api.env.JWT_SECRET="$(openssl rand -hex 32)" \
  --set api.env.DATABASE_HOST=postgres.namespace.svc.cluster.local \
  --set api.env.DATABASE_PASSWORD=strongpassword \
  --set api.env.ALLOWED_ORIGINS=https://seudominio.com \
  -n farm --create-namespace

Health Check¶

Verify the deployment is healthy after every release:

curl -fsS https://api.seudominio.com/api/health

Expected response:

{
  "status": "ok",
  "info": {
    "database": { "status": "up" },
    "memory_heap": { "status": "up" },
    "memory_rss": { "status": "up" },
    "storage": { "status": "up" }
  }
}

Any indicator with "status": "down" means a dependency is unreachable. Check database connectivity and Redis availability first.

First Admin User¶

After the first deployment there are no admin users. The first user to register gets the user role. Promote them to admin directly in the database:

UPDATE users
SET roles = '["admin","user"]'
WHERE username = 'your_username';

All subsequent role management can be done through the API using an admin JWT.

Security Hardening¶

• TLS: Terminate TLS at your load balancer or reverse proxy (nginx, Traefik, AWS ALB). The API itself does not handle TLS directly.
• Swagger UI: Restrict /api/docs at the network level if possible, in addition to the HTTP Basic Auth already in place. Consider disabling it entirely in production by not exposing the route.
• Secrets management: Use your platform's secret store (AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets) instead of plain .env files.
• Database: Use a dedicated PostgreSQL user with only the permissions required (SELECT, INSERT, UPDATE, DELETE on the farm database — no superuser).
• Redis: Enable authentication (requirepass) and restrict network access to the API container only.