Configuration reference¶

For a short, ordered walkthrough, start with Run your first server. This page is the detailed reference for environment variables, probes, exit codes, and bootstrap behavior. Its existing quick_start.md path is retained for incoming links.

Environment Variables¶

Hubuum accepts command-line options and HUBUUM_ environment variables; CLI options override the corresponding environment values. Supported credentials can also come from mounted files. Both binaries accept --secret-source file and --secret-file-root DIRECTORY, equivalent to HUBUUM_SECRET_SOURCE=file and HUBUUM_SECRET_FILE_ROOT. The default source remains environment.

File mode changes where supported secret values are read, while ordinary configuration keeps its existing inputs. Explicit database URL arguments override the selected source; missing required files do not fall back to environment credentials. See Secret Sources for the full precedence rules, environment/file mapping, and complete server, migration, and restore-executor deployment examples. Use hubuum-server --help or hubuum-admin --help to list each binary's CLI options.

Health Probes¶

Hubuum exposes unauthenticated probe endpoints for container schedulers and load balancers:

Probe paths bypass the client IP allowlist so platform health checks are not rejected before reaching the handler.

Local Docker Compose¶

The development Compose stack requires a local, untracked .env file instead of using a password committed to the repository:

printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 32)" > .env
docker compose --profile administration run --rm hubuum-migrate --migrate
docker compose up --build -d hubuum-restore-executor hubuum

This default uses one PostgreSQL login for the server, one-shot migrations, and the isolated restore executor. To opt into separate least-privilege roles, set HUBUUM_DATABASE_ROLE_MODE=split, provide unique migrator and runtime passwords and URLs as shown in .env.example, and initialize a fresh Compose database volume.

The API is published on 127.0.0.1:9999 and PostgreSQL on 127.0.0.1:9998; neither service listens on all host interfaces by default. The Hubuum container runs as the unprivileged hubuum user with a read-only root filesystem, all Linux capabilities dropped, and only a small temporary filesystem at /tmp.

The production image includes a /healthz health check, but long-lived server containers never run migrations. PostgreSQL client administration tools and the standalone Diesel CLI are not installed; use the image's hubuum-admin binary in a one-shot migration workload.

Server Configuration¶

Logs are newline-delimited JSON only and are configured through HUBUUM_LOG_LEVEL. Release builds include their Git SHA in the structured startup event; local builders may set HUBUUM_BUILD_GIT_SHA at compile time. See Structured Logging for fields and examples.

Access Control Configuration¶

Container note: The default HUBUUM_CLIENT_ALLOWLIST=127.0.0.1,::1 is loopback-only. In containerized setups, clients commonly arrive from bridge/network IPs, not loopback. For local/dev containers, set HUBUUM_CLIENT_ALLOWLIST=*. For production, prefer explicit CIDRs/IP ranges.

Proxy note: The client IP is resolved from the right of the [X-Forwarded-For..., peer] hop chain, so spoofed X-Forwarded-For values cannot take effect. When HUBUUM_TRUST_IP_HEADERS=true, configure HUBUUM_TRUSTED_PROXIES (preferred) or HUBUUM_TRUSTED_PROXY_HOPS. If neither is set, forwarded headers are ignored and the peer address is used.

Database Configuration¶

See Database Pool Tuning and Load Testing for connection budgeting, pool observability, and a repeatable k6 scenario. See PostgreSQL Database Roles for provisioning, grant diagnostics, and one-shot workload examples.

Administrators can inspect the selected storage backend and these effective pool settings at GET /api/v1/admin/config. The endpoint reports only whether the database URL is configured; it never returns the URL or credentials. See Application and Storage Boundary for the all-or-nothing backend contract.

Task System Configuration¶

Background workers and storage notification listeners participate in bounded graceful shutdown. See Background Worker Lifecycle for startup ownership, cancellation, task interruption, and pool-drop ordering.

Event And Audit Configuration¶

Event note: The canonical audit stream is always stored in the events table. External delivery workers default to disabled, and retention purge defaults to disabled because it deletes audit rows. See Event And Audit for audit querying, sink/subscription setup, delivery semantics, operational health, and retention behavior.

Export and Template Execution Configuration¶

Export/template note: These settings control async export task behavior, including stored output retention, template execution limits, and relation hydration guardrails. See Export API and Export Template Guide for the user-facing behavior these limits affect.

Backup and Restore Configuration¶

Backups and restore staging are unscoped administrator-only disaster-recovery operations. Destructive confirmation is disabled through the API and must run through hubuum-admin with the migrator credential. See Backup and Restore for the destructive confirmation flow, locking behavior, and export/import alternative for selective transfers.

Pagination Configuration¶

Clients can discover the effective pagination values, including deployment overrides, without authentication:

GET /api/v1/config

The response exposes only settings deliberately classified as client-safe:

{
  "pagination": {
    "default_page_limit": 100,
    "max_page_limit": 250
  }
}

Positive request limits above max_page_limit are clamped rather than rejected. Paginated responses include X-Page-Limit with the effective page size.

Authentication & Authorization¶

See Secret Sources for the mounted-file layout and rotation contracts, and External Authentication for LDAP scopes.

Token lifetime note: Newly issued tokens always receive an explicit expires_at. If a mint request omits it, the server applies HUBUUM_TOKEN_LIFETIME_HOURS. Clients can read the effective default without authentication from GET /api/v1/config at authentication.default_token_lifetime_hours; issuance responses return the authoritative expires_at. Explicit expirations must be in the future and no later than issuance plus HUBUUM_MAX_TOKEN_LIFETIME_HOURS; the public config also exposes this limit as authentication.max_token_lifetime_hours.

Login rate-limit note: These settings throttle failed logins across layered scopes with exponential backoff. For the full model, client-IP resolution behind proxies, and the admin endpoints for inspecting and releasing throttled scopes, see login_rate_limiting.md.

Token hash key note: If neither the compatible HUBUUM_TOKEN_HASH_KEY nor a key ring is configured, Hubuum generates an ephemeral key on startup and logs a warning. Tokens issued before restart will be invalid after restart. All API replicas must use the same ring. See Secret Sources for the staged multi-replica procedure.

For runtime roles, one-shot migrations, task recovery, database connection budgeting, and shared limiter behavior, see Distributed Deployment.

TLS Configuration¶

Note: TLS requires both certificate and key paths to be set. The rustls feature does not support encrypted keys with passphrases. Certificate chains must be regular PEM files no larger than 4 MiB; private keys must be regular PEM files no larger than 1 MiB.

Exit Codes¶

The application uses specific exit codes to indicate different failure modes, which helps with monitoring and automation:

Exit Code Usage Examples¶

# Check if server started successfully
./hubuum-server || echo "Server failed with exit code $?"

First-Time Bootstrap¶

On first startup with an empty database, Hubuum automatically creates:

• A default admin user (name: admin) with a randomly generated password
• A default admin group (named as per HUBUUM_ADMIN_GROUPNAME, default: admin)
• The admin user is added to the admin group

Important: The generated password is not printed or logged. Reset the password immediately after startup:

hubuum-admin --reset-password admin

Example Configurations¶

Development (HTTP)¶

export HUBUUM_BIND_IP="127.0.0.1"
export HUBUUM_BIND_PORT="8080"
export HUBUUM_LOG_LEVEL="debug"
export HUBUUM_DATABASE_URL="postgres://user:pass@localhost/hubuum_dev"
./hubuum-server

Production (HTTPS)¶

export HUBUUM_BIND_IP="0.0.0.0"
export HUBUUM_BIND_PORT="8443"
export HUBUUM_LOG_LEVEL="warn"
export HUBUUM_DATABASE_URL="postgres://hubuum:secure_password@db.example.com/hubuum_prod"
export HUBUUM_TLS_CERT_PATH="/etc/hubuum/certs/fullchain.pem"
export HUBUUM_TLS_KEY_PATH="/etc/hubuum/certs/privkey.pem"
export HUBUUM_ACTIX_WORKERS="8"
export HUBUUM_DB_POOL_SIZE="20"
./hubuum-server

Mounted Secrets¶

For a mounted directory containing database/url and token/key:

export HUBUUM_SECRET_SOURCE=file
export HUBUUM_SECRET_FILE_ROOT=/run/secrets/hubuum
export HUBUUM_REQUIRE_STABLE_TOKEN_HASH_KEY=true
hubuum-admin --migrate

Then run hubuum-admin --restore-executor and hubuum-server as separate supervised processes with the same environment. The default single database mode shares database/url; opt-in split uses a separate admin mount containing database/migration-url. See the complete mounted-secret Compose example and split-role mounts.

Docker Compose¶

Use single-host deployment for a complete installation with PostgreSQL, explicit migration sequencing, a restore executor, and optional frontend. For source development, use the repository's Compose configuration and the migration commands described above. A server-only Compose service does not provision its database or apply migrations.

See Also¶

• Development Setup - Git hooks, testing, and development workflow
• Authentication & Authorization Model - Principals, service accounts, tokens, and scopes
• External Authentication - Local and LDAP-backed identity scopes
• Permissions - Access control and authorization system
• Collection Hierarchy - Recursive collections, inherited permissions, and move rules
• Querying - API query syntax and filtering
• Search API - grouped discovery plus the structured resource-search DSL
• Query Support Matrix - Endpoint-by-endpoint filter and sort support
• Event And Audit - Audit log, event delivery, sink subscriptions, retention, and operational health
• Relationships - Working with object relationships
• Task System - Background workers, queue claiming, and task execution flow
• Backup and Restore - Full-system disaster recovery and selective-transfer alternatives
• Export API - Server-side export execution and templated output
• Remote Target API - Collection-scoped outbound subject actions
• Export Template Guide - Stored template syntax, context, and examples