Hubuum - A flexible asset management system

Hubuum (𒄷𒁍𒌝) in Sumerian translates as “axle” or “wheel assembly”¹.

Hubuum is a REST service that provides a shared interface for your resources.

Documentation website · Get started · Administration · API and clients

The website opens the latest released documentation. Select a release version or explicitly choose main for development documentation, and check client compatibility.

The latest release is Hubuum 0.0.18, published on October 6, 2026. Hubuum is suitable for evaluation and early deployments, but its API and configuration may change before 1.0.0. Pin deployments to an explicit version instead of using the moving main image tag. See Releases for recent changes and upgrade guidance.

Production deployments require PostgreSQL. An experimental, non-durable memory storage backend is available for disposable development and contract validation. Native release archives support Linux AMD64 and ARM64, macOS ARM64, and Windows AMD64; the Linux container image supports AMD64 and ARM64.

Linux archives contain stripped, statically linked executables and do not require a compatible system glibc, libpq, or OpenSSL installation. macOS and Windows archives bundle libpq and OpenSSL while retaining only their normal operating-system runtime dependencies.

Every archive includes hubuum-server, hubuum-admin, and hubuum-template-worker. Install matching versions of all three together; template rendering and validation require the worker executable beside the server and administrator binaries.

docker pull ghcr.io/hubuum/hubuum-server:v0.0.18

Run hubuum-admin --migrate as a one-shot workload before starting or upgrading the server. Container server entrypoints do not apply migrations. The default single database role mode uses the existing HUBUUM_DATABASE_URL; separate owner, migrator, and runtime roles are optional. Web restores also require a separately supervised hubuum-admin --restore-executor process.

• Follow Run your first server for a local evaluation and first-time administrator setup; see the configuration reference for all settings.
• Follow the deployment guide for Docker or Podman Compose installation.
• Follow the distributed deployment guide for multiple API/worker replicas, one-shot migrations, and optional shared login throttling.
• Download native binaries and checksums from the latest GitHub Release.
• Check a running instance at /healthz and /readyz.

The Alpine-based container image includes both the rustls and OpenSSL TLS backends. See the release guide for the complete tag scheme.

Most content management systems (CMDBs) are strongly opinionated. They provide fairly strict models with user interfaces designed for those models and all their data. This design may not be ideal for every use case.

CMDBs also like to be authoritative for any data they possess. The problem with this in this day and age, very often other highly dedicated systems are the authoritative sources of lots and lots data, and these sources typically come with very domain specific scraping tools.

With Hubuum you can...

• define your own data structures and their relationships.
• populate your data structures as JSON, and enforce validation when required.
• draw in data from any source into any object, structuring it as your organization requires.
• look up and search within these JSON structures in an efficient way, via a REST interface.
• offload the work of searching and indexing to Hubuum, and focus on your data.
• control permissions to one object set in one application instead of having to do it in multiple places.
• know that REST is your interface, no matter what data you are accessing.

Once upon a time your data was everywhere, each in its own silo. Now you can have it all in one place, and access it all through a single REST interface.

Hubuum is designed around the idea of classes and objects, where the classes are user-defined and optionally constrained by a JSON schema². Objects are instances of these classes and these classes only. If the class defines a schema, and the class requires validation against the schema, you are guaranteed that objects within that class conform to said schema.

The supported programmatic contract is HTTP/OpenAPI. The root Rust library is an internal application crate used to compose Hubuum's binaries, tests, and benchmarks; it is not a supported server embedding API. Rust clients should use hubuum-client-rust. See the Rust API boundary for the workspace package classifications and promotion policy.

• OpenAPI JSON is served at /api-doc/openapi.json.
• Swagger UI is served at /swagger-ui/ when built with the swagger-ui feature.

Most endpoints require bearer authentication.

Authorization: Bearer <token>

The identity model (human users and service-account principals), the token lifecycle, token scopes, and the request-authority gates are documented in docs/auth_model.md. Credential management requires fresh authentication approvals; CLI and frontend migration instructions are included. External identity scopes are documented in docs/external_auth.md.

Quick example:

curl -H "Authorization: Bearer <token>" http://localhost:8080/api/v1/iam/users

• The openapi.info.version value is tied to Cargo.toml package version (CARGO_PKG_VERSION).
• docs/openapi.json is the canonical committed spec for the current code.
• CI generates the spec and fails if it drifts from docs/openapi.json.
• CI also compares candidates with the latest stable release and blocks undocumented breaking changes; see the OpenAPI compatibility gate.
• The export endpoint is documented in docs/export_api.md.
• Stored template examples are documented in docs/export_template_guide.md.
• Remote target actions are documented in docs/remote_targets.md.
• Event audit and delivery behavior is documented in docs/events.md.
• Temporal history, actor capture, and GDPR anonymization are documented in docs/temporal_history.md.
• Personal and shared computed object fields are documented in docs/computed_fields.md.
• Numeric-safe class and object name addressing is documented in docs/name_addressing.md.
• Atomic RFC 6902 updates to raw object data are documented in docs/object_data_json_patch.md.
• Full-system disaster-recovery behavior is documented in docs/backup-restore.md.
• A ready-to-restore test corpus provides 3,000 objects across twelve classes with schemas, permissions, relations and history.
• Optional PostgreSQL owner, migrator, and runtime privilege boundaries are documented in docs/database_roles.md; the default topology retains one database login.
• Database pool sizing, observability, and load testing are documented in docs/performance.md.
• Non-HTTP compatibility snapshots and policy are documented in docs/operational_contracts.md.

• swagger-ui is enabled by default.
• To disable Swagger UI in production builds, build without default features (or without swagger-ui):
  • cargo build --no-default-features

• The default client allowlist is loopback-only (127.0.0.1,::1).
• In containers, inbound clients usually do not appear as loopback, so requests may be rejected unless you set HUBUUM_CLIENT_ALLOWLIST.
• HUBUUM_TRUST_IP_HEADERS defaults to false; only enable it behind trusted reverse proxies.
• For local/dev container setups, HUBUUM_CLIENT_ALLOWLIST=* is common.
• For production, prefer explicit CIDRs/IPs instead of *.

The client IP used for the allowlist, request logging, and login rate limiting is resolved from the right of the [X-Forwarded-For..., peer] hop chain, so attacker-supplied X-Forwarded-For values cannot be spoofed. Configure trust explicitly:

• HUBUUM_TRUST_IP_HEADERS=true is the master switch for honoring X-Forwarded-For.
• HUBUUM_TRUSTED_PROXIES (preferred): comma-separated proxy IPs/CIDRs. Hops in this set are skipped from the connection peer inward, and the first untrusted hop is taken as the client (e.g. HUBUUM_TRUSTED_PROXIES=10.0.0.0/8,192.168.0.0/16).
• HUBUUM_TRUSTED_PROXY_HOPS (fallback when no allowlist is set): the number of proxy hops in front of the server to skip from the right of the chain.
• If HUBUUM_TRUST_IP_HEADERS=true but neither of the above is set, forwarded headers are ignored and the connection peer address is used (forwarded values are never trusted blindly).

• HUBUUM_TOKEN_LIFETIME_HOURS controls bearer token lifetime and defaults to 24.
• HUBUUM_MAX_TOKEN_LIFETIME_HOURS bounds explicitly requested expirations and defaults to 8760 (365 days). It must be at least the default lifetime.
• When a token request omits expires_at, Hubuum stores issued + this default as the token's explicit expiry and returns it with the raw token.
• Explicit expirations must be later than issuance and no later than issued + the configured maximum lifetime.
• Clients can discover the effective default without authentication at GET /api/v1/config under authentication.default_token_lifetime_hours; the same object exposes authentication.max_token_lifetime_hours.
• Expired token rows are retained for HUBUUM_TOKEN_RETENTION_DAYS (default 30) and then deleted automatically in bounded batches.
• HUBUUM_TOKEN_RETENTION_PURGE_ENABLED enables the cleanup worker and defaults to true.
• HUBUUM_TOKEN_RETENTION_PURGE_INTERVAL_SECONDS (default 3600) and HUBUUM_TOKEN_RETENTION_PURGE_BATCH_SIZE (default 1000) control its cadence and batch size. The batch size must be at least 10.

Hubuum writes newline-delimited JSON logs. Set HUBUUM_LOG_LEVEL to control verbosity; see docs/logging.md for fields, request correlation, authorization events, and jq recipes.

Optional OpenTelemetry tracing exports a bounded span catalog through OTLP/HTTP over verified HTTPS. See docs/tracing.md for configuration, propagation, sampling, TLS, security, and failure behavior.

Login throttling is layered across three scopes - per (username, IP), per IP, and per subnet - so that single-account brute force, password spraying across many usernames from one host, and distributed spraying from one network are all throttled. When a scope crosses its threshold within the window it is locked out, and repeated lockouts back off exponentially (doubling from the backoff base up to the backoff maximum).

• HUBUUM_LOGIN_RATE_LIMIT_ENABLED master switch for login throttling; defaults to true.
• HUBUUM_LOGIN_RATE_LIMIT_MAX_ATTEMPTS max failed attempts per (username, IP) per window; defaults to 5.
• HUBUUM_LOGIN_RATE_LIMIT_MAX_ATTEMPTS_PER_IP max failed attempts per client IP per window; defaults to 20 (0 disables this scope).
• HUBUUM_LOGIN_RATE_LIMIT_MAX_ATTEMPTS_PER_SUBNET max failed attempts per client subnet per window; defaults to 100 (0 disables this scope).
• HUBUUM_LOGIN_RATE_LIMIT_WINDOW_SECONDS sliding window in seconds; defaults to 300.
• HUBUUM_LOGIN_RATE_LIMIT_BACKOFF_BASE_SECONDS first lockout duration in seconds; defaults to 300.
• HUBUUM_LOGIN_RATE_LIMIT_BACKOFF_MAX_SECONDS maximum lockout duration in seconds; defaults to 86400.
• HUBUUM_LOGIN_RATE_LIMIT_SUBNET_PREFIX_V4 IPv4 prefix length for subnet aggregation; defaults to 24.
• HUBUUM_LOGIN_RATE_LIMIT_SUBNET_PREFIX_V6 IPv6 prefix length for subnet aggregation; defaults to 64.
• HUBUUM_LOGIN_RATE_LIMIT_BACKEND selects local memory (default) or shared valkey state.
• HUBUUM_LOGIN_RATE_LIMIT_VALKEY_URL configures the shared Valkey/Redis service when selected.

Accurate throttling behind a reverse proxy depends on correct client-IP resolution; see Resolving the Real Client IP Behind a Proxy.

For the full model (scopes, backoff, client-IP resolution, and the admin endpoints for inspecting and releasing throttled scopes), see docs/login_rate_limiting.md.

• HUBUUM_TOKEN_HASH_KEY remains the compatible single-key configuration.
• Online rotation uses HUBUUM_TOKEN_HASH_ACTIVE_KEY_ID, HUBUUM_TOKEN_HASH_PREVIOUS_KEY_IDS, and one secret named HUBUUM_TOKEN_HASH_KEY_<ID> per configured ID.
• Set HUBUUM_REQUIRE_STABLE_TOKEN_HASH_KEY=true to reject startup instead of generating an ephemeral key when stable material is absent.
• If unset, Hubuum generates an ephemeral in-memory key at startup and logs a warning.
• With an ephemeral key, all existing bearer tokens become invalid after each restart.
• Keys must contain at least 32 bytes. IDs, staged rollout, mounted-file paths, rollback, and retirement checks are described in Secret Sources.

• The default container tags include both TLS backends and allow runtime selection with HUBUUM_TLS_BACKEND.
• The default image can also run without TLS if no certificate and key are configured.

The server and administrator support CLI options and environment configuration. Credentials can also come from mounted files using --secret-source file and --secret-file-root DIRECTORY (or HUBUUM_SECRET_SOURCE and HUBUUM_SECRET_FILE_ROOT). Environment-backed secrets remain the default. Secret Sources documents precedence, supported credentials, rotation, and server/admin deployment examples for both database role modes.

• The canonical environment-variable reference lives in docs/quick_start.md.
• Task-worker and async export-template tuning settings are documented there alongside the core server, DB, auth, and TLS settings.

• Single-host Docker/Podman Compose deployment scripts are documented in docs/deployment.md.
• Multi-replica topology and upgrade sequencing are documented in docs/distributed_deployment.md.
• The scripts support all-in-one frontend/backend installs, backend-only installs, managed Postgres, and an existing external Postgres URL.
• All-in-one installs expose both frontend and backend API hostnames; browser frontend flows can still use the frontend BFF routes.
• Published container images are used by default; local repository cloning/building is opt-in for source builds.
• Curl-style install, update, stop, and uninstall flows are supported; systemd service installation is opt-in.

Build the workspace with Cargo:

cargo build --all-features --locked

Repository tooling requires Python 3.11 or newer, selected as python3 on PATH, with no third-party Python packages. The local test environment is configured through .env:

source .env && ./run_tests.sh
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check

See docs/development.md for database setup, Git hooks, and the full development workflow.

Recent published releases:

Before upgrading:

• Read the target release's upgrade notes in CHANGELOG.md. CI certifies the adjacent stable upgrade and its declared recovery procedure.
• Upgrading from 0.0.17 requires downtime. Stop every API, worker, and restore executor, take a PostgreSQL snapshot with all writers stopped, then apply 2026-10-05-000001_collection_event_sinks and reconcile role grants. Start matching 0.0.18 server, administrator, and template worker binaries. The single-host updater uses hubuum-admin --migration-mode to select this offline sequence; take the snapshot before invoking it.
• Binary-only rollback to 0.0.17 is unsupported. Restore the pre-upgrade database snapshot before starting matching old binaries. Recovery loses writes made after the snapshot. Keep the old binaries, credentials, and snapshot until the upgrade is accepted. See upgrade and recovery.
• Backups now emit format 8; formats 6 and 7 remain accepted with legacy sink grants restored. Older servers cannot restore format 8. Upgrade all API, worker, and restore-executor processes before producing new backups.
• Collection integration setup requires ManageEventSubscription and ReadAudit. Shared global sinks need an explicit grant for each collection; existing collection/sink relationships receive grants during migration. Grants do not inherit. Credential-bearing webhooks and static headers require a fixed destination_url or url_secret_ref; subscription routing cannot redirect them. Collection-owned integrations survive the creator losing access, and related-collection deliveries omit resource snapshots.
• Storage adapter implementations must support sink ownership, direct grants, authorization, and configuration revisions in delivery claims.
• When upgrading from before 0.0.17, also apply its webhook-notification migration, accept nullable collection IDs in system delivery health, and follow its storage SDK and Treetop migration requirements below.
• Upgrade all eight storage adapter SDK crates together to 0.4.0, implement the new adapter capabilities, and use Utoipa 6 for schema composition. Treetop installations must upgrade REST and policy bundles to 0.1 and rebuild/re-sign format 2 bundles. See SDK migration and Treetop migration.
• Deployments upgrading from before 0.0.16 must first adopt its credential approval and task-discovery requirements. Update credential-management clients to obtain a single-use approval and send X-Hubuum-Credential-Approval. Follow the client guide and each intervening release's migration and backup requirements.
• When upgrading from before 0.0.15, update clients that change schema policy on nonempty classes to stage a revision, request impact analysis, and explicitly activate it. Review the JSON Schema limits for unsupported schemas and work budgets. Restart string-sorted pagination after upgrading.
• Treetop deployments upgrading from before 0.0.15 must add CancelTask policies. Review the external authorization query limits and storage SDK 0.3 changes in the changelog. Repository tooling now requires Python 3.11 or newer.
• Set matching backup and execution limits on API, worker, and administrator processes. Backups default to a 256 MiB byte ceiling and 1,000,000 captured rows; provision resources before raising these limits.

Full release notes are maintained in CHANGELOG.md. Pushing an annotated vX.Y.Z tag for a commit that has passed CI on main publishes a GitHub Release with native archives, SHA-256 checksums, SBOMs, provenance attestations, and versioned multi-architecture container images. Maintainer instructions are in docs/releasing.md.

Every release must update this README with the new version and release date, pinned container example, release links and highlights, and any changed installation or upgrade requirements. Include these updates in the release preparation pull request.

Hubuum is available under the MIT License.