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:

```bash
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:

```yaml
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:

```yaml
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
```yaml
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:

```yaml
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
```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
```caddyfile
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:

```bash
docker logs authentikate
```

Look for output like:
```
✅ Initial admin user created:
   Email: admin@authentikate.local
   Password: randomly-generated-password
```

## Updating

To update AuthentiKate:

```bash
# 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)
```bash
# 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
```bash
# 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 →](/guide/first-setup)
2. [Configure your first application →](/guide/applications)
3. [Set up email notifications →](/config/email)