Install using Docker Compose

View as Markdown

This is the easiest and fastest way to start using Krenalis locally.

Requirements

The steps in this page require Docker and Docker Compose.

Run Krenalis with one command

Quickly test Krenalis on your machine with minimal setup.

Navigate to the directory where you want to run and test Krenalis, then execute the following command:

Linux and macOS

mkdir -p storage && curl -fO "https://raw.githubusercontent.com/krenalis/krenalis/refs/tags/v0.30.0/compose.yaml" && if [ ! -f .env ]; then printf "KRENALIS_KMS=key:%s\n" "$(head -c 32 /dev/urandom | base64)" > .env; fi && docker compose up

Windows

$ErrorActionPreference = 'Stop'

New-Item -ItemType Directory -Force storage | Out-Null

Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/krenalis/krenalis/refs/tags/v0.30.0/compose.yaml" `
  -OutFile "compose.yaml"

if (-not (Test-Path .env)) {
    $bytes = New-Object byte[] 32
    [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
    "KRENALIS_KMS=key:$([Convert]::ToBase64String($bytes))" | Set-Content -Encoding utf8 .env
}

docker compose up -d

When the database initialization finishes, a message informs you that you can open the Krenalis Admin console at http://127.0.0.1:2022/admin.

Detailed steps

1. Create and enter into a directory where run Krenalis

Create a directory with an arbitrary name (e.g. my-krenalis-instance) and enter into it:

mkdir my-krenalis-instance
cd my-krenalis-instance

2. Download the Docker Compose

Linux and macOS

If you have Curl, you can just run:

curl -fO "https://raw.githubusercontent.com/krenalis/krenalis/refs/tags/v0.30.0/compose.yaml"

Windows

If you have Curl installed, run:

curl.exe -fO "https://raw.githubusercontent.com/krenalis/krenalis/refs/tags/v0.30.0/compose.yaml"

Or, alternatively, you can download this file:

https://raw.githubusercontent.com/krenalis/krenalis/refs/tags/v0.30.0/compose.yaml

and save it into the current working directory as compose.yaml.

3. Create the storage directory (optional)

The storage directory is a directory where from which Krenalis will import and export user data files. With the default configuration with Docker, the name must be storage.

mkdir storage

This step is optional, and it is required only if you want to test the local file import/export features of Krenalis. If not created, the Filesystem connector in Krenalis won't be available for use.

4. Create the .env file

Create an .env file and generate a random KMS master key for Krenalis:

Linux and macOS

printf "KRENALIS_KMS=key:%s\n" "$(openssl rand -base64 32 | tr -d '\n')" >> .env

Windows

$bytes = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
"KRENALIS_KMS=key:$([Convert]::ToBase64String($bytes))" | Add-Content -Encoding utf8 .env

This file stores the KMS master key used by Krenalis to protect its encrypted data. Keep it safe, and do not replace the existing KRENALIS_KMS value for an installation that is already in use. If you lose it, Krenalis will no longer be able to decrypt data protected with it.

5. Start Krenalis

Launch Krenalis with Docker Compose:

docker compose up

If you have previously started Krenalis using Docker Compose and want to reset it, perhaps for a clean installation or because you are running a new version of Krenalis, you must clear the Krenalis Docker data with docker compose down -v. This command removes containers and volumes, permanently deleting all stored data.

6. Open the Admin console

⏳ Wait until the initialization of Krenalis's databases is complete. This may take a few seconds.

Once the initialization is finished, as indicated by the console message stating that the Krenalis Admin console is available, you can access it by opening the address http://127.0.0.1:2022/admin/ in a browser.

Keep reading the documentation to see how to create your first workspace.