Installation

Overview#

AI Workforce OS ships as two application containers — an API service and a web (Next.js) service — backed by PostgreSQL and Redis. The reference deployment method is Docker Compose.

Purpose#

This page walks a System/IT Administrator through installing AI Workforce OS from scratch on a server you control, ending with a running system reachable over HTTPS.

Prerequisites#

• A Linux server (or VM) with Docker and Docker Compose installed.
• Node.js 20.x LTS and npm 11.x if you plan to build from source instead of using published images.
• A domain name you can point DNS for, if you want a public HTTPS URL.
• Outbound network access from the server (needed for AI provider calls, payment provider calls, and SSO if configured).

Step-by-Step Instructions#

Server requirements#

At minimum, provision a server with enough headroom for PostgreSQL, Redis, and both application containers running concurrently. Exact sizing depends on tenant count and concurrent users — start with a modest server and scale up if needed.

1. PostgreSQL 15 or later (the application uses Prisma migrations against PostgreSQL specifically — other databases are not supported).
2. Redis 7 or later (used for background job queues, rate limiting, and caching).
3. Node.js 20.x LTS runtime inside the application containers.

Docker installation#

1. Install Docker Engine and the Docker Compose plugin on your server.
2. Clone or copy the AI Workforce OS repository to the server.
3. Copy .env.example to .env and fill in the required values (see Environment Variables below).
4. Review infrastructure/docker-compose.yml, which defines four services: postgres (postgres:16-alpine), redis (redis:7-alpine), api, and web.

Docker Compose#

docker compose -f infrastructure/docker-compose.yml up -d

1. Start the stack with the command above. Compose waits for PostgreSQL and Redis health checks before starting the API service.
2. The API listens on port 3001 and the web application on port 3000 by default.
3. Run database migrations against the PostgreSQL container before first use (see your deployment runbook for the exact migration command for your release).
4. Confirm the API is healthy by checking its health endpoint, then confirm the web app loads in a browser.

Environment variables#

At minimum, set the following before starting the stack:

1. DATABASE_URL — PostgreSQL connection string.
2. REDIS_URL — Redis connection string.
3. JWT_ACCESS_SECRET, ACCESS_TOKEN_TTL, REFRESH_TOKEN_TTL — authentication token configuration.
4. ENCRYPTION_KEY — used to encrypt sensitive stored data (including MFA secrets). Treat this as a secret.
5. COOKIE_DOMAIN, COOKIE_SECURE, CORS_ORIGIN, WEB_APP_URL, NEXT_PUBLIC_API_URL — networking and cookie configuration matched to your domain.
6. MFA_ISSUER — the issuer name shown in employees’ authenticator apps.
7. LOCKOUT_THRESHOLD / LOCKOUT_DURATION — failed-login lockout policy.

Database#

1. Provision a PostgreSQL 15+ instance (the bundled postgres container, or your own managed database).
2. Point DATABASE_URL at it.
3. Apply Prisma migrations before starting the API for the first time.

Redis#

1. Provision a Redis 7+ instance (the bundled redis container, or a managed Redis service).
2. Point REDIS_URL at it. Redis backs background job queues and rate limiting — the API will not start correctly without it.

Storage#

1. Confirm your file/document storage configuration with your deployment team before going live.

SSL and DNS#

1. Point a DNS record at your server (for example app.yourcompany.com).
2. Terminate SSL/TLS in front of the containers using a reverse proxy (such as Nginx, Caddy, or a managed load balancer) — the application containers themselves do not manage certificates.
3. Set COOKIE_SECURE=true and WEB_APP_URL/NEXT_PUBLIC_API_URL to your HTTPS URLs once SSL is in place.

Production deployment#

1. Review Deployment for production-specific guidance (scaling, monitoring, and known operational gaps).
2. Run through the checklist in Deployment → Production Checklist before inviting real users.

Screens Involved#

Expected Results#

You should be able to open your web application URL in a browser and reach the AI Workforce OS login screen, with the API reachable behind it.

Not Available in This Release#

Common Mistakes#

• Forgetting to set ENCRYPTION_KEY before first startup, then rotating it later, which invalidates previously encrypted data such as MFA secrets.
• Leaving COOKIE_SECURE=false in a production HTTPS deployment, which can break session cookies.
• Skipping database migrations before first boot.
• Not setting push-notification credentials and then reporting "push notifications don’t work" — this is expected until VAPID/FCM credentials are configured.

Troubleshooting#

The API container will not start.#

Check that PostgreSQL and Redis are both reachable and healthy first — the API depends on both. Review container logs for the specific connection error.

The web app loads but API calls fail.#

Confirm NEXT_PUBLIC_API_URL in the web service matches the actual reachable API URL, and that CORS_ORIGIN on the API includes your web app’s origin.

Related Pages#

FAQ#

Best Practices#

• Keep .env secrets (JWT secret, encryption key, database credentials) out of version control.
• Run database migrations as a separate, auditable step before restarting application containers.
• Terminate TLS at a reverse proxy rather than inside the application containers.