authentikate/docs/guide/installation.md

Installation

AuthentiKate is designed to be deployed easily with Docker, making it perfect for homelab environments. This guide will walk you through different installation methods.

Quick Start with Docker

The fastest way to get AuthentiKate running is with Docker:

docker run -d \
  --name authentikate \
  -p 8080:8080 \
  -e APP_URL=http://localhost:8080 \
  -v authentikate_data:/var/www/html/storage \
  authentikate/authentikate:latest

AuthentiKate will be available at http://localhost:8080 with automatic setup completing in the background.

Docker Compose (Recommended)

For production use, we recommend using Docker Compose for better configuration management:

version: '3.8'

services:
  authentikate:
    image: authentikate/authentikate:latest
    container_name: authentikate
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      # Required
      APP_URL: https://auth.yourdomain.com
      APP_ENV: production
      
      # Database (SQLite by default)
      DB_CONNECTION: sqlite
      
      # Email (optional but recommended)
      MAIL_MAILER: smtp
      MAIL_HOST: your-smtp-server.com
      MAIL_PORT: 587
      MAIL_USERNAME: your-email@domain.com
      MAIL_PASSWORD: your-password
      MAIL_ENCRYPTION: tls
      MAIL_FROM_ADDRESS: auth@yourdomain.com
      MAIL_FROM_NAME: "AuthentiKate"
      
    volumes:
      - authentikate_data:/var/www/html/storage
      - authentikate_logs:/var/www/html/storage/logs
    
    # Optional: Use external database
    # depends_on:
    #   - postgres
    
    labels:
      # Traefik labels (if using Traefik)
      - "traefik.enable=true"
      - "traefik.http.routers.authentikate.rule=Host(`auth.yourdomain.com`)"
      - "traefik.http.routers.authentikate.entrypoints=websecure"
      - "traefik.http.routers.authentikate.tls.certresolver=letsencrypt"
      - "traefik.http.services.authentikate.loadbalancer.server.port=8080"

volumes:
  authentikate_data:
  authentikate_logs:

Environment Variables

Required Variables

Variable	Description	Example
APP_URL	The URL where AuthentiKate will be accessible	https://auth.yourdomain.com

Optional Variables

Variable	Default	Description
APP_ENV	production	Application environment
APP_DEBUG	false	Enable debug mode
DB_CONNECTION	sqlite	Database type (sqlite, mysql, postgres)
DB_DATABASE	/var/www/html/storage/database/database.sqlite	Database path/name

Database Options

SQLite (Default)

Perfect for most homelab setups. No additional configuration required.

PostgreSQL

For larger installations:

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: authentikate
      POSTGRES_USER: authentikate
      POSTGRES_PASSWORD: secure_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  authentikate:
    # ... other config
    environment:
      DB_CONNECTION: pgsql
      DB_HOST: postgres
      DB_DATABASE: authentikate
      DB_USERNAME: authentikate
      DB_PASSWORD: secure_password
    depends_on:
      - postgres

volumes:
  postgres_data:

MySQL/MariaDB

services:
  mysql:
    image: mariadb:10
    environment:
      MYSQL_DATABASE: authentikate
      MYSQL_USER: authentikate
      MYSQL_PASSWORD: secure_password
      MYSQL_ROOT_PASSWORD: root_password
    volumes:
      - mysql_data:/var/lib/mysql
  
  authentikate:
    # ... other config
    environment:
      DB_CONNECTION: mysql
      DB_HOST: mysql
      DB_DATABASE: authentikate
      DB_USERNAME: authentikate
      DB_PASSWORD: secure_password
    depends_on:
      - mysql

volumes:
  mysql_data:

Reverse Proxy Setup

Traefik

AuthentiKate works perfectly with Traefik. Add these labels to your Docker Compose:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.authentikate.rule=Host(`auth.yourdomain.com`)"
  - "traefik.http.routers.authentikate.entrypoints=websecure"
  - "traefik.http.routers.authentikate.tls.certresolver=letsencrypt"
  - "traefik.http.services.authentikate.loadbalancer.server.port=8080"

Nginx

server {
    listen 443 ssl http2;
    server_name auth.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy

auth.yourdomain.com {
    reverse_proxy localhost:8080
}

First Run

When you first start AuthentiKate, it will automatically:

1. Generate RSA Keys: Creates public/private key pair for JWT signing
2. Run Database Migrations: Sets up all necessary database tables
3. Create Admin User: Generates an initial admin account

The initial admin credentials will be displayed in the container logs:

docker logs authentikate

Look for output like:

✅ Initial admin user created:
   Email: admin@authentikate.local
   Password: randomly-generated-password

Updating

To update AuthentiKate:

# Pull the latest image
docker pull authentikate/authentikate:latest

# Stop and remove the old container
docker stop authentikate
docker rm authentikate

# Start with the new image
docker-compose up -d

Your data will be preserved in the Docker volumes.

Backup

Database Backup (SQLite)

# Create backup
docker exec authentikate cp /var/www/html/storage/database/database.sqlite /tmp/backup.sqlite
docker cp authentikate:/tmp/backup.sqlite ./authentikate-backup-$(date +%Y%m%d).sqlite

# Restore backup
docker cp ./authentikate-backup-20240101.sqlite authentikate:/tmp/restore.sqlite
docker exec authentikate cp /tmp/restore.sqlite /var/www/html/storage/database/database.sqlite

Full Data Backup

# Backup all data
docker run --rm -v authentikate_data:/data -v $(pwd):/backup alpine tar czf /backup/authentikate-data-$(date +%Y%m%d).tar.gz -C /data .

# Restore data
docker run --rm -v authentikate_data:/data -v $(pwd):/backup alpine tar xzf /backup/authentikate-data-20240101.tar.gz -C /data

Next Steps

Once AuthentiKate is running:

1. Complete the first setup →
2. Configure your first application →
3. Set up email notifications →