Codakey
Play
← Back to goauthentik/authentik

How to Deploy & Use goauthentik/authentik

authentik Deployment and Usage Guide

1. Prerequisites

System Requirements

  • Docker Engine 20.10+ or Kubernetes 1.24+
  • Docker Compose v2.0+ (for Compose deployments)
  • 4GB RAM minimum (8GB recommended for production)
  • 2 CPU cores minimum
  • 20GB disk space (SSD recommended)

Required Services

authentik requires two external services:

  • PostgreSQL 12+ (database)
  • Redis 6+ (cache/sessions)

Tools

  • openssl (for generating secrets)
  • kubectl and helm v3+ (for Kubernetes deployments)
  • git (for configuration management)

2. Installation

Method A: Docker Compose (Recommended for Small/Test Setups)

Create a dedicated directory and download the official compose file:

mkdir authentik && cd authentik
curl -L -o docker-compose.yml https://goauthentik.io/docker-compose.yml
curl -L -o .env https://goauthentik.io/.env.example

Generate a secure secret key:

echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 36)" >> .env

Pull and start the services:

docker compose pull
docker compose up -d

Run database migrations:

docker compose run --rm server migrate

Create the initial admin user:

docker compose run --rm server create_admin

Access the web interface at http://localhost:9000 (or https://localhost:9443).

Method B: Kubernetes (Helm Chart)

Add the authentik Helm repository:

helm repo add authentik https://charts.goauthentik.io
helm repo update

Create a values.yaml file:

authentik:
  secret_key: "changeme-generate-a-secure-key"
  postgresql:
    password: "secure-db-password"
  
server:
  ingress:
    enabled: true
    hosts:
      - authentik.example.com

postgresql:
  enabled: true
  auth:
    password: "secure-db-password"

redis:
  enabled: true

Install the chart:

helm install authentik authentik/authentik -f values.yaml

Method C: AWS CloudFormation

Deploy using the official templates:

aws cloudformation create-stack \
  --stack-name authentik \
  --template-url https://goauthentik.io/aws/cloudformation.yaml \
  --parameters ParameterKey=AdminEmail,ParameterValue=admin@example.com

3. Configuration

Core Environment Variables

Create a .env file or configure via your deployment method:

# Required
AUTHENTIK_SECRET_KEY=your-generated-secret-key-min-50-chars
AUTHENTIK_POSTGRESQL__HOST=postgresql
AUTHENTIK_POSTGRESQL__NAME=authentik
AUTHENTIK_POSTGRESQL__USER=authentik
AUTHENTIK_POSTGRESQL__PASSWORD=secure-password
AUTHENTIK_REDIS__HOST=redis

# Optional: Email configuration (required for password resets)
AUTHENTIK_EMAIL__HOST=smtp.example.com
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USERNAME=authentik@example.com
AUTHENTIK_EMAIL__PASSWORD=email-password
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__FROM=authentik@example.com

# Optional: Error reporting
AUTHENTIK_ERROR_REPORTING__ENABLED=true
AUTHENTIK_ERROR_REPORTING__ENVIRONMENT=production

# Optional: GeoIP (for location-based policies)
AUTHENTIK_GEOIP__PATH=/geoip/GeoLite2-City.mmdb

Docker Compose Volume Configuration

Ensure persistent storage in docker-compose.yml:

volumes:
  database:
    driver: local
  redis:
    driver: local
  media:
    driver: local
  certs:
    driver: local
  custom-templates:
    driver: local

Blueprints (Infrastructure as Code)

authentik supports YAML blueprints for declarative configuration. Place blueprint files in /blueprints/ (mounted volume):

# example-blueprint.yaml
version: 1
entries:
  - model: authentik_core.user
    identifiers:
      username: admin
    attrs:
      name: Administrator
      is_superuser: true
    state: present

4. Build & Run

Development Setup

For local development with hot-reload:

git clone https://github.com/goauthentik/authentik.git
cd authentik

# Install Python dependencies (requires Python 3.11+)
poetry install

# Install Node dependencies for the web UI
cd web && npm install && cd ..

# Run database (PostgreSQL + Redis)
docker compose -f local-docker-compose.yml up -d postgresql redis

# Run migrations
poetry run python -m manage migrate

# Start backend
poetry run python -m manage runserver 0.0.0.0:8000

# In another terminal, start frontend
cd web && npm run watch

Access the development instance at http://localhost:8000.

Production Run

For production Docker Compose:

# Start all services
docker compose up -d

# View logs
docker compose logs -f server worker

# Check health
docker compose ps

Key Management Commands

# Create backup
docker compose run --rm server backup

# Restore from backup
docker compose run --rm server restore /backups/backup-file.json

# Update check
docker compose run --rm server version

# Shell access
docker compose run --rm server shell

5. Deployment

Small/Home Lab (Docker Compose)

  • Use the standard Docker Compose setup
  • Enable automated backups via cron: 
    0 2 * * * cd /opt/authentik && docker compose run --rm server backup > /dev/null 2>&1

Enterprise/Production (Kubernetes)

  • Use the Helm chart with external PostgreSQL/Redis for high availability
  • Configure multiple server replicas: 
    server:
  replicas: 3
  resources:
    requests:
      memory: "2Gi"
      cpu: "1000m"
  • Deploy Outposts (LDAP/RADIUS proxies) as separate deployments for high availability

Cloud Platforms

DigitalOcean Marketplace:

  1. Navigate to Marketplace and select authentik
  2. Choose droplet size (4GB RAM minimum)
  3. Configure DNS to point to droplet IP
  4. Complete setup via web interface at http://<droplet-ip>:9000/if/flow/initial-setup/

AWS (CloudFormation):

  • Deploys with Application Load Balancer
  • RDS PostgreSQL backend
  • Auto-scaling group for server instances
  • S3 bucket for media storage

Reverse Proxy Configuration

Nginx:

server {
    listen 443 ssl;
    server_name auth.example.com;
    
    location / {
        proxy_pass http://authentik-server:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Traefik:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.authentik.rule=Host(`auth.example.com`)"
  - "traefik.http.services.authentik.loadbalancer.server.port=9000"

6. Troubleshooting

Database Connection Errors

Symptom: FATAL: database "authentik" does not exist Solution:

docker compose run --rm server migrate

Secret Key Issues

Symptom: ImproperlyConfigured: SECRET_KEY must be at least 50 characters Solution: Generate a new key:

openssl rand -base64 36
# Update .env and restart: docker compose up -d

Permission Denied on Volumes

Symptom: PermissionError: [Errno 13] Permission denied: '/media' Solution: Fix volume permissions:

docker compose run --rm server chown -R 1000:1000 /media /certs

Outpost Connection Failures

Symptom: Outposts show as "Unhealthy" Solution: Ensure network connectivity between outpost and server:

# From outpost container
curl http://authentik-server:9000/api/v3/root/config/

Email Not Sending

Symptom: Password reset emails not delivered Solution: Verify email configuration:

docker compose run --rm server test_email admin@example.com

High Memory Usage

Symptom: OOM kills on worker containers Solution: Limit worker concurrency in .env:

AUTHENTIK_WORKER__CONCURRENCY=2

Blueprint Import Errors

Symptom: ValidationError during blueprint apply Solution: Check blueprint syntax against API:

docker compose run --rm server shell -c "from authentik.blueprints.v1.importer import Importer; Importer('blueprint.yaml').validate()"

Upgrade Failures

Symptom: Migration errors after upgrade Solution: Always backup before upgrading:

docker compose run --rm server backup
docker compose pull
docker compose up -d
docker compose run --rm server migrate
← Project overviewView alternatives to goauthentik/authentik →