authentikate/docs/quick-start/index.md

# Installation

Docker is the recommended way to deploy AuthentiKate. Although [Manual Installation](/quick-start/manual-deployment)
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](#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](https://laravel.com/docs/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.

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

```yaml [docker-compose.yml]
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
```

```bash [docker run]
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
```

```yaml [ansible]
- 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](https://laravel.com/docs)

:::

## Database Configuration {#database-configuration}

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

::: code-group

```env [MySQL]
DB_CONNECTION=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_DATABASE=authentikate
DB_USERNAME=your-username
DB_PASSWORD=your-password
```

```env [PostgreSQL]
DB_CONNECTION=pgsql
DB_HOST=your-postgres-host
DB_PORT=5432
DB_DATABASE=authentikate
DB_USERNAME=your-username
DB_PASSWORD=your-password
```

```env [SQLite]
DB_CONNECTION=sqlite
DB_DATABASE=/var/www/html/database/database.sqlite
```

```env [MariaDB]
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

```env [SMTP]
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"
```

```env [Gmail]
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"
```

```env [Mailgun]
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"
```

```env [SendGrid]
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](/user-guide/).