authentikate/docs/quick-start/index.md

Installation

Docker is the recommended way to deploy AuthentiKate. Although Manual Installation instructions are also provided.

Prerequisites

• Docker and Docker Compose installed
• Reverse proxy for SSL certificates. Most apps will not work with an OIDC provider that is not serving over SSL.

Additional services

• A database server (MySQL, PostgreSQL). SQLite is the default, in which case you can skip this step. See Database Configuration
• SMTP server for email functionality. Emails are not necessary for sending invites since you can copy the invite link and send it. But it's a nice to have.
• Domain name and SSL certificate (recommended for production)

Docker Setup

Note

All our Laravel app docker images are running Laravel Octane for better performance.

Caution

You have to set the APP_KEY environment variable. Otherwise when your container restarts you'll have a different key and lose access.

# Generate a random 32-character base64 key
openssl rand -base64 32

Caution

You need to bind to the /app/storage/oauth volume. This is where the public and private encryption keys are stored. If these change, all the authentication will be messed up.

Warning

You should to bind to the /app/storage/avatars volume so you don't lose all avatars on restart.

::: code-group

services:
  authentikate:
    image: gitgud.foo/thegrind/authentikate:latest
    container_name: authentikate
    ports:
      - "8000:8000"
    environment:
      - APP_ENV=production
      - APP_DEBUG=false
      - APP_KEY=base64:your-32-character-secret-key-here
      - APP_URL=https://your-domain.com
      - DB_CONNECTION=mysql|postgres|sqlite
      - DB_HOST=database # Only needed for postgres/mysql
      - DB_PORT=3306 # Only needed for postgres/mysql
      - DB_DATABASE=authentikate # Only needed for postgres/mysql
      - DB_USERNAME=authentikate # Only needed for postgres/mysql
      - DB_PASSWORD=secure-password-here # Only needed for postgres/mysql
    volumes:
      - ./keys:/app/storage/oauth
    restart: unless-stopped

docker run -d \
  --name authentikate \
  -p 8000:8000 \
  -e APP_ENV=production \
  -e APP_DEBUG=false \
  -e APP_KEY=base64:your-32-character-secret-key-here \
  -e APP_URL=https://your-domain.com \
  -e DB_CONNECTION=mysql \
  -e DB_HOST=database \
  -e DB_PORT=3306 \
  -e DB_DATABASE=authentikate \
  -e DB_USERNAME=authentikate \
  -e DB_PASSWORD=secure-password-here \
  -v ./keys:/app/storage/oauth \
  --restart unless-stopped \
  gitgud.foo/thegrind/authentikate:latest

- name: Deploy AuthentiKate container
  community.docker.docker_container:
    name: authentikate
    image: gitgud.foo/thegrind/authentikate:latest
    ports:
      - "8000:8000"
    env:
      APP_ENV: production
      APP_DEBUG: "false"
      APP_KEY: "base64:your-32-character-secret-key-here"
      APP_URL: "https://your-domain.com"
      DB_CONNECTION: mysql
      DB_HOST: database
      DB_PORT: "3306"
      DB_DATABASE: authentikate
      DB_USERNAME: authentikate
      DB_PASSWORD: secure-password-here
    volumes:
      - ./keys:/app/storage/oauth
    restart_policy: unless-stopped
    state: started

After deploying the container

Check the logs for the admin user email and password. Log in and change your credentials.

You can now start using AuthentiKate.

Some common configuration options are shown below.

For more configuration options you can refer to the Laravel Documentation

:::

Database Configuration

AuthentiKate supports multiple database backends. Choose the configuration that matches your setup:

::: code-group

DB_CONNECTION=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_DATABASE=authentikate
DB_USERNAME=your-username
DB_PASSWORD=your-password

DB_CONNECTION=pgsql
DB_HOST=your-postgres-host
DB_PORT=5432
DB_DATABASE=authentikate
DB_USERNAME=your-username
DB_PASSWORD=your-password

DB_CONNECTION=sqlite
DB_DATABASE=/var/www/html/database/database.sqlite

DB_CONNECTION=mysql
DB_HOST=your-mariadb-host
DB_PORT=3306
DB_DATABASE=authentikate
DB_USERNAME=your-username
DB_PASSWORD=your-password

:::

Mail Configuration

Configure mail settings for user notifications and password resets:

::: code-group

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-server.com
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-email-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@your-domain.com
MAIL_FROM_NAME="AuthentiKate"

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-gmail@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-gmail@gmail.com
MAIL_FROM_NAME="AuthentiKate"

MAIL_MAILER=mailgun
MAILGUN_DOMAIN=your-domain.com
MAILGUN_SECRET=your-mailgun-api-key
MAIL_FROM_ADDRESS=noreply@your-domain.com
MAIL_FROM_NAME="AuthentiKate"

MAIL_MAILER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-sendgrid-api-key
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@your-domain.com
MAIL_FROM_NAME="AuthentiKate"

:::

Next Steps

After installation, you can:

1. Access the web interface at your configured URL
2. Create your first admin user
3. Configure OIDC clients and SSO integrations
4. Set up user authentication providers

For detailed configuration and usage instructions, see the User Guide.