Skip to main content
Halite is configured through environment variables at startup and through in-app settings stored in the database. This page covers both. For a guided walkthrough of the in-app Settings page, see Settings.

​
Environment variables

Set these in your .env file (which docker compose loads automatically) or pass them directly to the container.

​
Database

​
string
required
SQLAlchemy async database URL.For compose.yml (Postgres): postgresql+asyncpg://halite:halite@db:5432/haliteFor compose.sqlite.yml (homelab): sqlite+aiosqlite:////data/halite.db

​
Sessions

​
string
required
Signing key for session cookies. Must be at least 32 characters. Generate one with ./scripts/gen-bootstrap-secret.sh.
​
integer
default:"480"
How long a session remains valid after the last request, in minutes. Defaults to 480 (8 hours).
​
boolean
default:"true"
Controls the Secure flag on the session cookie.
  • false — cookie is sent over plain HTTP (use for local Docker testing at http://localhost:8080)
  • true — cookie is only sent over HTTPS (use in production behind a TLS proxy)
The compose.yml profile defaults this to true; compose.sqlite.yml defaults it to false.
​
string
default:"halite_session"
Name of the session cookie.

​
Networking

​
string
default:"0.0.0.0"
The host address uvicorn binds to.
The shipped Docker images launch uvicorn with a hardcoded --host 0.0.0.0 --port 8080, so this setting has no effect in the provided compose setups. To change the host port, remap the ports: entry in your compose file (e.g. "9000:8080").
​
integer
default:"8080"
The port uvicorn listens on.
The shipped Docker images launch uvicorn with a hardcoded --host 0.0.0.0 --port 8080, so this setting has no effect in the provided compose setups. To change the host port, remap the ports: entry in your compose file (e.g. "9000:8080").
​
string
default:""
Recognized by the settings loader but not currently wired into request handling. Reserved for future use.

​
Logging

​
string
default:"info"
Logging verbosity. Standard Python log level names: debug, info, warning, error, critical.

​
Audit

​
boolean
default:"false"
Recognized by the settings loader but not currently wired into request handling. Reserved for future use — intended to enable recording of read-only requests in the audit log, but the flag is not consumed anywhere in the current codebase.

​
SPA serving

​
string
Filesystem path to the built React SPA (dist/). When set, the backend serves the SPA from this directory. When unset, SPA serving is disabled (useful if you serve the frontend separately).The provided Docker image sets this to /app/frontend/dist at build time.

​
In-app settings (database-backed)

These settings are stored in a singleton AppSettings row in the database and managed on the Settings page. They are not environment variables — changing them does not require a container restart.

​
Salt-API connection

The Salt-API connection is configured entirely through the in-app Settings page. The SALT_API_* lines in .env.example are stale placeholders not read by current builds.

​
Inventory refresh

​
Pollers

​
Logging format

The application startup currently calls setup_logging with a hardcoded "json" value, so current builds always emit JSON logs regardless of the log_format setting. The LOG_FORMAT entry in .env.example is stale and not read by the application.

​
Bootstrap admin

On first boot, when no users exist in the database, Halite automatically creates a default admin account:
  • Username: admin
  • Password: changeme
  • Forced password change: Yes — you are required to set a new password on first login.
This account is created unconditionally from values hardcoded in bootstrap.py. The BOOTSTRAP_ADMIN_USERNAME and BOOTSTRAP_ADMIN_PASSWORD lines in .env.example are stale and not read by the application.
Change the bootstrap admin password on first login before exposing Halite to a network.

​
Stale .env.example entries

The following entries appear in .env.example but are not read by the application in current builds: