Docker Compose Setup for Authensor

Docker Compose is the fastest way to run the complete Authensor stack locally. In under five minutes, you get the control plane, PostgreSQL, and optional Redis running together with proper networking and environment configuration.

Prerequisites

Install Docker and Docker Compose (v2). Ensure ports 3000 (control plane), 5432 (PostgreSQL), and 6379 (Redis) are available on your machine.

Compose File Structure

The Docker Compose configuration defines three services: the Authensor control plane, PostgreSQL, and Redis.

PostgreSQL uses the official postgres:16 image with a named volume for data persistence. Set the database name, user, and password through environment variables. Include a health check that uses pg_isready so dependent services wait for the database to be ready.

Redis uses the official redis:7-alpine image. For local development, no authentication is needed. Add a health check using redis-cli ping.

The Authensor control plane builds from the project Dockerfile or uses the published image. It depends on both PostgreSQL and Redis, waiting for their health checks to pass. Environment variables configure the database URL, Redis URL, Aegis and Sentinel feature flags, and an admin API key.

First Run

Start the stack with docker compose up. On first run, the control plane runs database migrations automatically, creating the tables for policies, receipts, and API keys.

Create your first API key using the CLI: npx authensor keys create --role admin --name "dev-key". This key authenticates all subsequent API calls.

Loading Policies

Place your YAML policy files in a policies directory and mount it as a volume in the control plane container. Use the CLI to load them: npx authensor policy apply ./policies/default.yaml.

Development Workflow

Run docker compose up -d to start the stack in the background. Make changes to policies locally, reload them with the CLI, and test against the running control plane. Logs are accessible with docker compose logs -f authensor.

Teardown

Run docker compose down to stop all services. Add the -v flag to also remove database volumes if you want a clean start. For development, keep volumes to preserve your policies and test data between sessions.

This setup mirrors production architecture at a single-node scale, making it suitable for integration testing and local development against the full safety stack.