Apantio AI

Deploy with Docker Compose

Run Apantio AI on one server with Docker Compose. You'll configure PostgreSQL, Redis, file storage, and HTTPS, then verify the deployment before going live.

Prerequisites

  • Docker Engine 24 or later with Compose v2
  • Node.js 22 or later, to generate secrets
  • at least 4 CPU cores, 8 GB RAM, and durable disk storage
  • public DNS names for the dashboard and voice gateway
  • Twilio and OpenAI accounts for live calls

Configure the environment

git clone https://github.com/stephano-cell/apantio-ai.git
cd apantio
node scripts/generate-env.mjs

The script copies .env.example to .env and fills every PostgreSQL role password and internal secret with a random 64-character value. It won't overwrite an existing .env unless you pass --force, which also replaces every secret in it.

Then open .env and set APP_BASE_URL, OPENAI_API_KEY, and your Twilio credentials. Services build their database connection strings from the role passwords, so you don't need to write any database URLs.

Compose sets STORAGE_PROVIDER=local by default. The admin and worker mount the same persistent storage_data volume at /var/lib/apantio/storage.

Do not expose a stack that still uses the example passwords or change-me secrets.

Start Apantio AI

docker compose --env-file .env up -d --build
docker compose ps

The migrator applies PostgreSQL migrations before the admin and worker services start. Health checks hold dependent services until their prerequisites are ready.

The admin readiness response includes database and storage checks. The worker readiness response includes PostgreSQL, Redis, and storage status.

Apantio AI does not run monitoring containers. Application logs remain available through docker compose logs, and the health endpoints continue to work.

Choose a storage backend

The default local provider supports a single Docker host. Back up the storage_data volume with PostgreSQL and restore both from the same recovery point.

Use S3 when the admin and worker run on different hosts. Set these values in .env:

STORAGE_PROVIDER=s3
S3_BUCKET=apantio
S3_REGION=us-east-1
S3_ENDPOINT=
S3_ACCESS_KEY_ID=replace-with-access-key
S3_SECRET_ACCESS_KEY=replace-with-secret-key
S3_FORCE_PATH_STYLE=false

AWS workloads may omit the access-key variables when the container can use an AWS credential role.

MinIO remains available through a Compose profile. Configure the S3 variables for MinIO, then start the stack with the profile:

STORAGE_PROVIDER=s3
S3_ENDPOINT=http://minio:9000
S3_BUCKET=apantio
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=replace-with-a-long-minio-password
S3_FORCE_PATH_STYLE=true
docker compose --env-file .env --profile minio up -d --build

For local email inspection, start Mailpit:

docker compose --env-file .env --profile development up -d mailpit

Export OpenTelemetry data

OpenTelemetry export is disabled when OTEL_EXPORTER_OTLP_ENDPOINT is empty. To send traces, metrics, and OpenTelemetry logs to PostHog, add these values to .env:

OTEL_EXPORTER_OTLP_ENDPOINT=https://us.i.posthog.com/i
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your_posthog_project_token_here

Use your regional PostHog host and project token. Apantio AI appends /v1/traces, /v1/metrics, and /v1/logs to the base URL. You can use the same variables with another OTLP-compatible backend.

Restart the application containers after changing the values:

docker compose --env-file .env up -d

Direct product analytics and voice-gateway error reporting use their own PostHog configuration.

Verify the deployment

curl -fsS http://127.0.0.1:3000/api/health/ready
curl -fsS http://127.0.0.1:3001/health/ready
docker compose logs --since=10m admin worker voice-gateway

The default service ports bind to localhost. Put public traffic through Caddy or another trusted reverse proxy.

Production checklist

  • replace all development credentials and limit .env permissions
  • use production HTTPS values for APP_BASE_URL, VOICE_GATEWAY_BASE_URL, and NEXT_PUBLIC_WEB_CALL_ENDPOINT
  • configure WEB_CALL_ALLOWED_ORIGINS with exact dashboard and website origins
  • configure off-host PostgreSQL and file-storage backups
  • run a restore drill before accepting production traffic
  • restrict PostgreSQL, Redis, and optional MinIO ports to private networks
  • monitor admin, worker, voice gateway, queue, database, and object-storage health
  • pin image versions before planned upgrades

Upgrades

git pull --ff-only
docker compose --env-file .env build
docker compose --env-file .env up -d

Back up PostgreSQL and the configured storage backend before upgrading. Review new migrations and environment variables before restarting services.