Self-hosted backend

Run the AiMANAC API on your machine or VPS with Docker. The published image includes PostgreSQL (pgvector), Redis, and the server.

1. Prerequisites

Install Docker Desktop (or Docker Engine + Compose v2 on Linux). Start Docker before continuing.

2. Compose file

Create a working directory and save the following as docker-compose.customer.yml:

# Customer-facing stack: pull ghcr.io/everplay-tech/aimanac-server:latest + Postgres + Redis.
# Copy to your server, add a .env (see docker/README.md and .env.customer.example), then:
#   docker compose -f docker-compose.customer.yml up -d

services:
  postgres:
    image: pgvector/pgvector:pg16
    restart: unless-stopped
    environment:
      POSTGRES_USER: aimanac
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
      POSTGRES_DB: aimanac
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U aimanac"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --requirepass "${REDIS_PASSWORD}"
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend:
    image: ghcr.io/everplay-tech/aimanac-server:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:${PORT:-3000}:3000"
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"

volumes:
  pgdata:
  redisdata:

Pull the image first if you prefer:

docker pull ghcr.io/everplay-tech/aimanac-server:latest

3. Environment file

In the same directory as the compose file, create .env. The backend service loads it via env_file: .env.

Required variables (replace placeholders; keep DATABASE_URL and REDIS_URL in sync with your passwords):

# Rename to .env next to your docker-compose.customer.yml (or merge into your env file).
# Generate secrets: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

POSTGRES_PASSWORD=change-me-strong-db-password
REDIS_PASSWORD=change-me-strong-redis-password
PORT=3000

DATABASE_URL=postgresql://aimanac:change-me-strong-db-password@postgres:5432/aimanac?connection_limit=10&pool_timeout=30&connect_timeout=5
REDIS_URL=redis://:change-me-strong-redis-password@redis:6379

JWT_SECRET=change-me-64-char-hex-minimum
JWT_REFRESH_SECRET=change-me-another-64-char-hex
ENCRYPTION_KEY=exactly-32-char-encryption-key

# Optional: copy additional keys from backend/.env.example (AI providers, Microsoft OAuth, etc.)

Use strong unique values for POSTGRES_PASSWORD, REDIS_PASSWORD, JWT_SECRET, JWT_REFRESH_SECRET, and ENCRYPTION_KEY. The Redis URL must include the password: redis://:${REDIS_PASSWORD}@redis:6379.

4. Start the stack

docker compose -f docker-compose.customer.yml up -d

The backend container runs Prisma migrations on start, then serves the API. First pull may take a few minutes.

5. Verify health

curl http://localhost:3000/health

Expect JSON with "status":"OK", schemaVersion, and database/redis up.

6. Connect the app

Open AiMANAC → Settings → Backend URL. Use your API base (include /api/v1):

• Same machine: http://localhost:3000/api/v1
• LAN: http://YOUR_IP:3000/api/v1
• VPS: http://YOUR_SERVER_IP:3000/api/v1 (or HTTPS if you terminate TLS in front)

By default the compose file binds the API to 127.0.0.1 only. To reach it from other devices, adjust the ports mapping in the compose file (e.g. "3000:3000") and secure the host with a firewall or reverse proxy.

← Home