Installation

This guide will walk you through getting Alarik up and running on your system. The recommended approach is using Docker, which handles all dependencies and provides a consistent environment across platforms.

Prerequisites

Before you begin, make sure you have the following installed:

• Docker (version 20.10 or later recommended)
• Docker Compose (usually included with Docker Desktop)

Quick Start with Prebuilt Images

The easiest way to get started is using the prebuilt Docker images from GitHub Container Registry. Create a docker-compose.yml file:

services:
  alarik:
    image: ghcr.io/achtungsoftware/alarik:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - API_BASE_URL=http://localhost:8080
      - CONSOLE_BASE_URL=http://localhost:3000
      - ADMIN_USERNAME=alarik
      - ADMIN_PASSWORD=alarik
      - JWT=YOUR_SECURE_JWT_KEY
      - ALLOW_ACCOUNT_CREATION=false
    volumes:
      - alarik-storage:/app/Storage

  console:
    image: ghcr.io/achtungsoftware/alarik-console:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NUXT_PUBLIC_API_BASE_URL=http://localhost:8080
      - NUXT_PUBLIC_CONSOLE_BASE_URL=http://localhost:3000
      - NUXT_PUBLIC_ALLOW_ACCOUNT_CREATION=false
    depends_on:
      - alarik

volumes:
  alarik-storage:

Then start the services:

docker compose up -d

Once started, the following services will be available:

Configuration

Alarik is configured through environment variables passed directly to each Docker container.

Alarik API Variables

API_BASE_URL=http://localhost:8080

CONSOLE_BASE_URL=http://localhost:3000

ALARIK_REGION=us-east-1

ALARIK_FSYNC=true

Console Variables

The console uses Nuxt and requires the NUXT_PUBLIC_ prefix for environment variables:

NUXT_PUBLIC_API_BASE_URL=http://localhost:8080

NUXT_PUBLIC_CONSOLE_BASE_URL=http://localhost:3000

NUXT_PUBLIC_ALLOW_ACCOUNT_CREATION=false

Authentication

JWT=YOUR_SECURE_JWT_KEY

A default admin user is always created on first startup. You can customize the credentials using these variables:

ADMIN_USERNAME=alarik

ADMIN_PASSWORD=alarik

S3 Access Keys

You can configure default S3 access keys for the admin account:

DEFAULT_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE

DEFAULT_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Default Buckets

DEFAULT_BUCKETS=uploads,media,logs

Account Settings

ALLOW_ACCOUNT_CREATION=false

OIDC SSO (optional)

Alarik supports signing in via one or more external OIDC identity providers (Okta, Google Workspace, Microsoft Entra, Keycloak, Auth0, etc.) alongside local username/password login - local login keeps working unchanged whether or not any SSO providers are configured.

Unlike most of Alarik's configuration, OIDC providers are not set via environment variables. They're managed entirely from the console by an admin, under Admin → OIDC Providers, and stored as part of Alarik's own control-plane metadata - so providers can be added, edited, or removed without restarting the deployment. Any number of providers can be configured at once; each one shows up as its own "Sign in with {name}" button on the login page.

For each provider, an admin supplies:

All providers share a single callback URL, which only needs to be registered once per provider in each identity provider's own app configuration:

{API_BASE_URL}/api/v1/auth/oidc/callback

How SSO logins map to Alarik accounts

By default, a local user must already exist with its username set to the value the identity provider sends in the email claim. The first successful SSO login for that email links the two accounts to that specific provider; every login after that is matched directly by that link, even if the username is later changed. If no matching account exists, the login is rejected.

Linking (and account creation, below) only ever happens when the identity provider marks the email as verified (email_verified claim) - an unverified email is rejected outright, since it would otherwise let anyone claim an arbitrary address.

SSO auto-provisioning

When ALLOW_ACCOUNT_CREATION=true (the same switch that enables the console's signup form), an SSO login with no matching account automatically creates one instead of being rejected:

• username is set to the verified email from the identity provider
• the display name comes from the provider's name claim, falling back to the email
• the account is created as a regular (non-admin) user and linked to the provider immediately
• no usable local password is set - the account starts SSO-only; a password can be added later via account settings

When ALLOW_ACCOUNT_CREATION is unset or anything other than true, SSO can never create accounts - it strictly signs in users that already exist.

See the Admin OIDC Providers API reference to manage providers programmatically instead of through the console.

Test the API

Using the AWS CLI:

aws s3 --endpoint-url http://localhost:8080 ls

Or with curl:

curl http://localhost:8080

Create a Test Bucket

aws s3 --endpoint-url http://localhost:8080 mb s3://my-first-bucket

Building from Source (Advanced)

If you prefer to build natively without Docker, you'll need Swift 6.2 or later installed on your system.

cd alarik
swift run

For the web console (requires Node.js):

cd console
npm install
npm run dev