Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.halite-app.com/llms.txt

Use this file to discover all available pages before exploring further.

Halite ships as a single Docker image that serves both the built React SPA and the FastAPI backend on LISTEN_PORT (default 8080). Two compose files are provided — choose the one that fits your environment.

​
Compose profiles

When to use: Production-shaped deployments where you want a durable, externally manageable database.compose.yml defines two services:
ServiceImageRole
dbpostgres:18Database — data persisted to the halite-pg named volume
appBuilt from DockerfileBackend + SPA — waits for db healthcheck before starting
The app service requires db to pass its pg_isready healthcheck before it starts. The halite-pg volume persists Postgres data across container restarts.
docker compose -f compose.yml up --build
The app service exposes port 8080 on the host. COOKIE_SECURE defaults to true in this profile.

​
The Docker image

The Dockerfile uses a two-stage build:
  1. Frontend stage (node:20-alpine) — runs npm ci && npm run build to produce the compiled SPA in /app/frontend/dist.
  2. Runtime stage (python:3.13-slim) — installs the backend package, copies the built frontend assets, runs alembic upgrade head on startup, then launches uvicorn.
Both compose files accept an optional BUILD_HASH build argument. When provided (e.g. BUILD_HASH=$(git rev-parse HEAD) docker compose build), the value is stamped into the frontend build and shown in the sidebar footer. When omitted, the UI displays “Dev”.

​
TLS and reverse proxy

Halite does not terminate TLS itself. Run it behind a reverse proxy (nginx, Caddy, Traefik, etc.) and set these environment variables: 
# Require HTTPS for the session cookie — set this when fronted by TLS
COOKIE_SECURE=true
TRUSTED_PROXIES is a recognized setting (comma-separated IP addresses or CIDR ranges) but is not currently wired into request handling. It is reserved for future use.
COOKIE_SECURE=true means the browser will only send the session cookie over HTTPS. If you set this on a plain-HTTP deployment, you will not be able to log in.
The app listens on LISTEN_HOST (default 0.0.0.0) and LISTEN_PORT (default 8080). Configure your proxy to forward to that port.

​
Healthcheck

Both compose profiles configure the same healthcheck: 
python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/healthz')"
The /healthz endpoint returns 200 once the app is ready to serve traffic. Use this URL for load-balancer or orchestrator health probes. See Configuration for the full environment variable reference.