Self-hosting Authensor with Docker

Authensor is fully self-hostable. The control plane runs as a single Node.js process backed by PostgreSQL. This guide covers deploying with Docker Compose for production use.

Prerequisites

• Docker and Docker Compose installed
• A machine with at least 1 GB of RAM
• A domain name (optional, for HTTPS)

Docker Compose setup

Create a docker-compose.yaml:

version: "3.8"
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: authensor
      POSTGRES_USER: authensor
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U authensor"]
      interval: 5s
      timeout: 3s
      retries: 5

  control-plane:
    image: ghcr.io/authensor/control-plane:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://authensor:${DB_PASSWORD}@postgres:5432/authensor
      AUTHENSOR_AEGIS_ENABLED: "true"
      AUTHENSOR_SENTINEL_ENABLED: "true"
      API_KEY_ADMIN: ${ADMIN_API_KEY}
      API_KEY_INGEST: ${INGEST_API_KEY}
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  pgdata:

Environment variables

Create a .env file (never commit this):

DB_PASSWORD=your-secure-database-password
ADMIN_API_KEY=your-admin-api-key
INGEST_API_KEY=your-ingest-api-key

Start the stack

docker compose up -d

The control plane runs database migrations on first start. Check the logs:

docker compose logs control-plane

Verify the deployment

curl -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  http://localhost:3000/api/health

You should see a JSON response with the version number and database status.

Connect your SDK

Point your SDK at the self-hosted control plane:

const guard = createGuard({
  controlPlane: 'http://your-server:3000',
  apiKey: process.env.AUTHENSOR_API_KEY,
});

Policies are now managed centrally through the control plane API. The SDK fetches the active policy on startup and caches it locally.

Production hardening

For production deployments:

• Put the control plane behind a reverse proxy (nginx, Caddy) with TLS
• Use a managed PostgreSQL instance for reliability
• Set up database backups for receipt storage
• Configure log aggregation for operational visibility
• Set resource limits on the Docker containers
• Use secrets management (Vault, AWS Secrets Manager) instead of .env files

Updating

Pull the latest image and restart:

docker compose pull control-plane
docker compose up -d control-plane

Migrations run automatically on startup. The control plane is backward compatible with existing receipt data.