Install with Docker

This is the authoritative installation guide. It takes you from a machine with Docker to a running KolleK instance with your first account created. Expect the whole thing to take around fifteen minutes.

The repository's docker/README.md documents the same procedure from the operator's side and is kept in sync with the code. If this page and that file ever disagree, trust docker/README.md.

Before you start

You need:

A machine with Docker Engine 24 or newer and the Compose plugin (docker compose).
A copy of the KolleK repository, cloned or downloaded.
Ten minutes of attention for the environment file. It is where the mistakes that matter happen.

Nothing else. The stack brings its own MySQL database, and sessions, cache, and the queue are database backed, so there is no Redis to install.

Install

Create your environment file

From the repository root, copy the Docker environment template:

cp .env.docker.example .env

This file drives the whole stack. You will edit it in the next two steps.

Generate the application key

Generate a key and copy the output:

docker compose run --rm app php artisan key:generate --show

Paste the printed value into .env as APP_KEY. This key encrypts your data at rest. Set it now and never change it later. A changed key makes every encrypted field and every session permanently unreadable. Read The application key and encryption before going further if you have not yet.

Review passwords and the URL

In .env, change DB_PASSWORD and DB_ROOT_PASSWORD from their placeholder values, and set APP_URL to the address your users will visit. The default is http://localhost:8000, which is fine for a first try on your own machine.

Start the stack

Build and start everything:

docker compose up -d --build

The first build takes a few minutes. When it finishes, the web container applies the database migrations automatically and the instance comes up at your APP_URL.

Create your first account

Open the URL in a browser and use the registration page to sign up. This creates your personal user and your first account, exactly as described in Create your account.

::screenshot{label="Registration page of a freshly installed instance"}

Grant yourself instance administrator access

If you want the server wide administration panel, grant your user the flag:

docker compose exec app php artisan kollek:make-instance-administrator you@example.com

See Grant instance administrator access for what this does and does not give you.

What is actually running

The Compose stack starts four containers. Three of them run the same KolleK image in different roles, chosen by the CONTAINER_ROLE environment variable:

app serves the web application through nginx and PHP. It is the only container that runs database migrations, and it does so on boot.
queue processes background jobs (email, deliveries, logging) from the high, default, and low queues.
scheduler triggers the daily maintenance jobs described in Scheduled maintenance jobs.

The fourth container is mysql, running MySQL 8.4.

Your data lives in two named Docker volumes, independent of the containers: db-data for the database and storage-data for uploaded photos and documents. Containers can be rebuilt and replaced freely; the volumes persist.

Note

All three application containers must share the same .env, and above all the same APP_KEY. The Compose file already arranges this. Keep it that way if you customize the setup.

If you prefer to run migrations yourself

By default the web container migrates the database every time it boots, which keeps upgrades hands off. If you want manual control, set RUN_MIGRATIONS=false in .env, then run migrations yourself when needed:

docker compose exec app php artisan migrate --force

Where to next

Walk through Configure your instance to understand what else .env controls.
Make email work in Set up email delivery. Until you do, invitations and sign in links go to a log file instead of an inbox.
Set up backups before you put real data in.

Was this page useful?