Install with Docker¶

This is the minimum needed to bring Axium up with plain docker run and log in for the first time. It is the right choice for an evaluation or a single VM. For anything you intend to keep, prefer Docker Compose so the configuration lives in a file.

Installing on Google Cloud?

Do not follow this guide. Use the Google Cloud installer, which creates Cloud SQL, deploys both services to Cloud Run and verifies the installation for you.

1. Log in to the registry¶

The images are private. One Quay token works for both core and ui:

docker login quay.io

2. Create a network¶

The core needs to reach PostgreSQL by name:

docker network create axium

3. Start PostgreSQL¶

docker run -d --name axium-db --network axium \
  --restart unless-stopped \
  -e POSTGRES_USER=axium \
  -e POSTGRES_PASSWORD=change-this \
  -e POSTGRES_DB=axium-api \
  -v axium-pgdata:/var/lib/postgresql/data \
  postgres:17-alpine

The axium-pgdata volume is the only state you have to preserve. See Backup & restore.

4. Generate the master key¶

The core encrypts the provider credentials it stores in the database with a master key. Generate it once and store it in your password manager:

openssl rand -hex 32

The master key cannot be rotated

If MASTER_ENCRYPTION_KEY is lost or changed, none of the stored provider credentials can be decrypted and all of them have to be entered again by hand. Treat it like a database backup: without it the backup is incomplete.

5. Start the core¶

docker run -d --name axium-core --network axium \
  --restart unless-stopped \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://axium:change-this@axium-db:5432/axium-api \
  -e MASTER_ENCRYPTION_KEY=<the 64 hex characters from the previous step> \
  -e AXIUM_LICENSE=<your 40-character license> \
  quay.io/axiumlab/core:latest

DATABASE_URL and MASTER_ENCRYPTION_KEY are the only mandatory variables. Without either of them, or with a key that is not exactly 64 hexadecimal characters, the process refuses to start. Everything else is optional and documented in Environment variables.

On the first startup the core waits for PostgreSQL (up to 30 seconds), installs the schema itself and creates the initial user. Restarting it repeats nothing.

6. Start the ui¶

docker run -d --name axium-ui --network axium \
  --restart unless-stopped \
  -p 3001:3001 \
  -e API_URL=http://localhost:3000/v1 \
  quay.io/axiumlab/ui:latest

API_URL is the ui's only variable and it is resolved by the user's browser, not by the container. It has to be the URL the core is reached at from the outside. In a real deployment that is something like https://axium-api.your-domain.com/v1. An internal Docker name such as http://axium-core:3000/v1 does not work, even though the ui container can resolve it. It must end in /v1 with no trailing slash. See Web console.

7. Check that it is up¶

curl http://localhost:3000/v1/health          # {"status":"ok"}
curl http://localhost:3000/v1/install/status  # {"state":"installed", ...}

You need both. /v1/health answers ok even if the schema installation failed, so the one that confirms Axium is usable is /v1/install/status. If it returns anything other than installed, check the logs:

docker logs axium-core | grep '\[install\]'

The full list of states is in Health checks.

8. Log in¶

Open http://localhost:3001 and continue with First login.