Bare metal (Ansible)
The same single-host stack as Docker Compose, installed and managed for you on one Linux host — Docker set up, secrets vaulted, and the stack running as a systemd service.
The same single-host stack as Docker Compose, installed and managed for you. Use this when you want the Compose deployment without running the commands by hand: the playbook installs Docker, vaults your secrets, drops the Compose bundle at /opt/orbtrace, and registers a orbtrace.service systemd unit (so it restarts on boot) that runs docker compose up -d. Same architecture and same one-host footprint as the Compose path — just delivered as a repeatable, automated install. It targets a single Linux host; it is not a multi-machine cluster installer.
Check the Installation preparation page for the host prerequisites first. Everything lands on one machine — the playbook just automates the Docker Compose stack:
One Linux host — systemd: orbtrace.service
Data flow
The playbook stands up the same Compose stack — app, Doris, Postgres and Valkey — on one host and runs it as orbtrace.service. The only piece you run separately is the Collector that writes your telemetry into Doris; the app reads it back and serves the UI on :8080.
Because all of Doris runs on this one host, size it from your volume — the Capacity planning calculator gives the CPU/memory/disk a single-host deploy needs.
- 1
Prepare the host
One Linux host (Debian/Ubuntu 22.04+ or RHEL/Rocky 9+) with SSH access from your control machine, and the 8 GB+ RAM from the prerequisites.
- 2
Open the playbook from the bundle
The Ansible playbook ships inside the deploy bundle Nivorbit gave you (alongside your pull token):
tar xzf orbtrace-2.1.0.tar.gz && cd orbtrace-2.1.0/ansible ansible-galaxy collection install -r requirements.yml cp inventory.example.ini inventory.ini $EDITOR inventory.iniPut your target host in
inventory.ini. The example file is annotated. The one-timeansible-galaxystep installs thecommunity.dockercollection the playbook uses to log the host in toghcr.io, so the private image pulls during the run. - 3
Set variables and encrypt them
Copy the annotated variables template, fill it in, then encrypt it with Ansible Vault. The playbook's pre-flight refuses to run with placeholder secrets:
cp group_vars/all.example.yml group_vars/all.yml $EDITOR group_vars/all.yml ansible-vault encrypt group_vars/all.ymlSet
orbtrace_ghcr_usernameandorbtrace_ghcr_token(your registry pull token) andorbtrace_postgres_password. Leaveorbtrace_doris_passwordempty — the bundled Doris runs its root account passwordless, and a value here breaks the first boot. Addorbtrace_license_keyonly if you've outgrown the free COMMUNITY edition. - 4
Run the playbook
ansible-playbook -i inventory.ini site.yml --ask-vault-passIdempotent — safe to re-run.
- 5
Health-check
curl http://<host>:8080/actuator/healthExpect
{"status":"UP"}. Continue to First login.
What the playbook sets up
The run is idempotent and leaves the host in this state:
| On the host | What it is |
|---|---|
| Docker Engine + Compose plugin | Installed from Docker's official repo (skip with orbtrace_install_docker: false if already present) |
/opt/orbtrace/ | The deploy bundle; the stack runs from its compose/ subdirectory |
.env | Rendered from your vaulted variables — never checked in |
orbtrace.service (systemd) | A unit that runs docker compose up -d and starts the stack on boot |
| Kernel sysctls | vm.max_map_count, swap off — the Doris prerequisites, set on the host |
Variables reference
Set these in group_vars/all.yml (vault-encrypted). The pre-flight refuses to run with placeholder secrets.
| Variable | Required? | What it is |
|---|---|---|
orbtrace_ghcr_username / orbtrace_ghcr_token | yes (online) | Your Nivorbit registry pull credentials |
orbtrace_postgres_password | yes | Postgres password for the bundled database |
orbtrace_doris_password | leave empty | The bundled Doris root is passwordless — a value breaks first boot |
orbtrace_bootstrap_admin_username | recommended | The email that becomes your admin (see Authentication) |
orbtrace_license_key | optional | .orblic token; empty = free COMMUNITY edition (Licensing) |
orbtrace_secret_kek | recommended | Encrypts AI-provider keys stored from the admin panel at rest |
orbtrace_airgapped | for offline | true loads images from the bundle's tars instead of pulling (Air-gapped install) |
The shipped group_vars/all.example.yml documents every variable inline.
Day-2 operations
Everything runs as a normal systemd service and Compose project on the host:
sudo systemctl status orbtrace # is it up?
sudo systemctl restart orbtrace # full-stack restart
sudo journalctl -u orbtrace -f # live logs (compose output)
cd /opt/orbtrace/compose
sudo docker compose ps # per-container viewUpgrade: unpack the new bundle on your control machine, bump orbtrace_version in group_vars/all.yml, and re-run ansible-playbook site.yml. The playbook replaces the stack and restarts the service; the app applies any new Doris schema migrations on the next boot. Back up first (below).
Production notes for a single host
- Where your data lives. Postgres and Doris write to Docker named volumes on this host (under
/var/lib/docker/volumes). That is the only copy — this host is the failure domain, so back it up off-box. - Back up before every upgrade. Schedule a nightly
docker exec orbtrace-postgres pg_dump …and a DorisBACKUP SNAPSHOTto remote/object storage (details in the post-install checklist). Migrations are forward-only, so a backup is your rollback. - TLS + firewall. Front the app with the bundled Caddy (
orbtrace_compose_profiles: [edge], publishes 80/443) or your own reverse proxy; expose only 8080 (or 443) to users and keep Doris's 8030/9030 on loopback. - Need HA or to scale past one host? This path can't — one host is the failure domain. Move to the Kubernetes (Helm) path.
Wire your telemetry in — stand up an OTel Collector, or add the doris exporter to your existing OTel pipeline (Integration patterns) — then finish with the post-install checklist.