Quickstart

Prerequisites: Docker and Docker Compose must be installed. A reachable salt-api (rest_cherrypy) endpoint is optional for first boot — the UI starts without Salt configured and degrades gracefully until you wire it up in Settings.

Clone the repo and copy the env template

git clone <this repo>
cd halite
cp .env.example .env

Generate a cookie secret

Run the helper script and paste its output as the value of COOKIE_SECRET in your .env file.

./scripts/gen-bootstrap-secret.sh
# Paste the output as COOKIE_SECRET in .env

Choose a database profile and bring it up

SQLite (homelab)
Postgres

Open .env and swap DATABASE_URL to the commented-out SQLite line:

# DATABASE_URL=postgresql+asyncpg://halite:halite@db:5432/halite
DATABASE_URL=sqlite+aiosqlite:////data/halite.db

Then start the stack:

docker compose -f compose.sqlite.yml up --build

The SQLite profile runs a single container with no external database dependency — ideal for a homelab or personal use.

Keep the default DATABASE_URL in .env as-is (it points to the db service in the compose stack):

DATABASE_URL=postgresql+asyncpg://halite:halite@db:5432/halite

Then start the stack:

docker compose -f compose.yml up --build

This profile brings up two services: db (Postgres 18) and app. The app service waits for db to pass its healthcheck before starting.

docker compose automatically loads values from .env in the project directory — no shell exports are needed.

Browse to http://localhost:8080/ and sign in with the bootstrap credentials:

Username: admin
Password: changeme

These credentials are built into the app (bootstrap.py) and are created on first boot when no users exist in the database. On first login you are required to set a new password. The BOOTSTRAP_ADMIN_* entries in .env.example are stale — they are not read by the application.

Verify without the browser

You can confirm the stack is healthy with three curl calls:

# 1. Log in — stores the session cookie in cookies.txt
curl -s -X POST http://localhost:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"changeme"}' -c cookies.txt | jq

# 2. Confirm the session resolves to your user
curl -s http://localhost:8080/api/auth/me -b cookies.txt | jq

# 3. Read the tail of the audit log
curl -s "http://localhost:8080/api/audit?limit=10" -b cookies.txt | jq

Before exposing Halite to a network, change the bootstrap admin password and set COOKIE_SECURE=true in your .env file. COOKIE_SECURE=true is required for HTTPS-fronted deployments; with it set, the session cookie will not be sent over plain HTTP.

Get Started

Concepts

Features

Develop

Verify without the browser

Next steps

Configuration

Settings

​Verify without the browser

​Next steps

Configuration

Settings

Verify without the browser

Next steps