anbaric-hosting

Run your own Anbaric platform. This package re-exports anbaric-cloud-hosting (the platform library) and provides the anbaric-hosting command that boots the full service: the public API and pages, the internal entry point for apps, the queue dispatcher, and the app build layer.

npm install -g anbaric-hosting
ANBARIC_DATABASE_URL=postgres://user:pass@host:5432/anbaric anbaric-hosting

The platform is configured entirely through environment variables:

| Variable | Purpose | Default | | --- | --- | --- | | ANBARIC_DATABASE_URL | Postgres connection string (jobs, documents, queue, system tables) | — required | | ANBARIC_HOSTING_PORT | public entry point (auth-walled: API, dashboard, app proxy) | 8787 | | ANBARIC_INTERNAL_PORT | internal entry point (unauthenticated workflow APIs; never expose publicly) | 8788 | | ANBARIC_PLATFORM_PUBLIC_URL | public URL, used for login callbacks | http://localhost:8787 | | ANBARIC_PLATFORM_INTERNAL_URL | how deployed apps reach the internal entry point | http://localhost:<internal port> | | ANBARIC_TENANT | tenant this platform serves (returned to the CLI on login) | — | | ANBARIC_BUILD_LAYER | docker (needs a docker socket) or fargate (AWS); unset disables app deployment | unset | | ANBARIC_AUTHENTICATOR | stub, or the module name of an auth plugin exposing createAuthenticator() | unset (auth disabled) | | ANBARIC_PLUGINS | comma-separated plugin module names providing the dashboard's pages and widgets | anbaric-plugins/state-machines | | ANBARIC_STUB_USER | the fixed identity the stub authenticator signs everyone in as | local-admin | | ANBARIC_CLI_KEY_LOOKUP_URL / _SECRET | verify CLI keys against a central key registry instead of the local database (hosted-platform feature; self-hosts leave unset) | unset (keys local) | | ANBARIC_APPS_DIR | working directory for app bundles | /tmp/anbaric-apps | | ANBARIC_DISPATCH_INTERVAL_MS | queue dispatch interval | 1000 |

With ANBARIC_BUILD_LAYER=docker: ANBARIC_APP_BASE_IMAGE, ANBARIC_DOCKER_NETWORK. With fargate: the ANBARIC_AWS_* set (cluster, subnets, security group, Cloud Map namespace, ECR repository, S3 build bucket, CodeBuild project, base image, app execution role, log group) — see the anbaric-cloud-hosting README for the full table and the reference OpenTofu that provisions it all.

The two entry points matter for security. The public port serves everything behind session/token authentication. The internal port serves only the workflow resources (jobs, queue, consumers, state-machines, documents, secrets, /ping) with no authentication — it must only ever be reachable by deployed apps (same docker network, same task, or a security-group rule).

Health check: GET /ping → {"status":"ok"} on both ports.

The dashboard and plugins

The root dashboard is assembled from plugins — the platform loads the modules named in ANBARIC_PLUGINS, and every page (including the homepage) comes from one of them. Left unset, the platform loads anbaric-plugins/state-machines, which registers the / Dashboard with the state-machines and jobs overview.

A plugin is a small source package exporting a plugin object with pages (nav-visible containers, keyed by path — plugin paths win over deployed apps of the same name) and widgets (React components rendered into a page, each optionally backed by a server-side data function). To add one, install it and name it alongside the default:

npm install some-plugin-package
ANBARIC_PLUGINS=some-plugin-package,anbaric-plugins/state-machines anbaric-hosting

The platform compiles each plugin's components at boot and serves them to the dashboard, which renders them with the platform's own React and design system — the dashboard build itself is plugin-agnostic, so adding a plugin is configuration only, never a rebuild. See the anbaric-plugins README for the full contract and how to write one.

The self-host flow

Self-hosting is deliberately simple — one platform, everything local, no external control plane:

1. Domain: run on localhost, or put the platform behind your own domain/TLS (a reverse proxy or the reference AWS setup in the repo's gitops/); set ANBARIC_PLATFORM_PUBLIC_URL accordingly.
2. Authentication — three choices:
   • Unset: no auth at all. Every request is anonymous; fine on a trusted network or laptop.
   • ANBARIC_AUTHENTICATOR=stub: every request is authenticated as one fixed identity with no credential check — the whole auth-dependent surface (/whoami, CLI keys, the dashboard) works without an identity provider. Development only: anyone who can reach the platform is that user.
   • Your own provider: publish or vendor a module exporting createAuthenticator() : Authenticator — authenticate returns [User, Tenant] for a valid session and writes its own redirect/401 otherwise — and name it in ANBARIC_AUTHENTICATOR. Any OIDC/SAML/ anything provider fits behind that contract.
3. CLI access: anbaric login, choose Other and enter your platform URL. The browser authorization, keypair issuance, key storage and verification all happen on your platform — no central service involved. ANBARIC_TENANT is an optional label your platform reports to the CLI ("Logged into tenant X"); leave it unset for a single-tenant install.

Anbaric Cloud (the hosted product) layers central login, organizations and edge routing on top of exactly this platform — none of it lives in the open source packages, and none of it is needed to self-host.