Deploying Octez stack with Ansible: the octez collection

cmehat · August 3, 2026, 4:44pm

If you run Tezos infrastructure on plain VMs or bare metal — testnets, baking rigs, monitoring fleets — there is now an Ansible collection that packages the whole Octez stack as reusable roles: infra_nomadic_labs.octez.

It deploys and operates Octez nodes, bakers, accusers, DAL nodes, the teztale archiver, and a handful of supporting services (status page, oauth2-proxy, Netdata), all as systemd services on Debian/Ubuntu hosts.

Where to get it

GitLab (source of truth): tezos-infra / ansible-collection-octez · GitLab
Ansible Galaxy: Ansible Galaxy

Install from Galaxy:

ansible-galaxy collection install infra_nomadic_labs.octez

Or pin to a tag from the Git source (recommended for ops repos):

# requirements.yml
collections:
  - name: infra_nomadic_labs.octez
    source: https://gitlab.com/tezos-infra/ansible-collection-octez.git
    type: git
    version: v0.5.4

Requirements: Ansible ≥ 2.15; target hosts on Debian 12 (bookworm) or Ubuntu 22.04+ (x86_64 — the collection ships the official x86_64 release binaries).

What’s in the box

Nine roles, each documenting its variables in its own defaults/main.yml:

Role	Purpose
`node`	`octez-node` as a systemd service: network config, zcash params, snapshot bootstrap, helper Makefile
`baker`	`octez-baker` + `octez-client` wallet setup, delegate registration, staking, consensus/companion keys
`accuser`	`octez-accuser` as a systemd service
`dal`	Data Availability Layer node, including attester profile wiring
`artifact_download`	Fetch Octez binaries from releases or GitLab CI artifacts
`teztale_archiver`	teztale archiver feeding a teztale server
`status_page`	HTML configuration/status page for a deployment
`oauth2_proxy`	oauth2-proxy GitLab-SSO auth endpoint for fronting web-facing extras (e.g. the status page)
`netdata`	Netdata agent with Octez-aware configuration

A minimal playbook looks like:

- hosts: tezos_nodes
  roles:
    - role: infra_nomadic_labs.octez.artifact_download
    - role: infra_nomadic_labs.octez.node
    - role: infra_nomadic_labs.octez.baker
      when: octez_baker_enabled | default(false) | bool

Key capabilities

Each claim below is backed by the role code; the activation variable and value are given as (variable_name:value).

Flexible binary sourcing

One octez_version variable, three interpretations, selected by the version type:

Official releases from octez.tezos.com (octez_version_type:release, with octez_version a version string like v25.0-rc1)
A specific tezos/tezos GitLab CI job artifact (octez_version_type:gitlab_tezos_job, the default, with octez_version a numeric job id)
A tezos/tezos git ref — commit hash or tag — resolved to a CI job automatically (octez_version_type:gitlab_tezos_git_ref; requires a GITLAB_TOKEN env var on the controller)

This makes it as easy to run a release as it is to canary a specific master commit across a testnet fleet.

Node: network selection, history mode, snapshot bootstrap

Any network by name — mainnet and ghostnet are built in, anything else resolves through https://teztnets.com/<network> (tezos_network:<network-name>)
History mode selection rendered into the node config (octez_history_mode:rolling — or full / archive)
First-run snapshot bootstrap: an empty datadir is bootstrapped from a tzinit snapshot automatically, as a fire-and-forget systemd unit you can watch with journalctl -u octez-node-bootstrap -f (octez_node_bootstrap_snapshot:true, the default). The mirror is configurable (octez_node_bootstrap_snapshot_base_url:"https://snapshots.eu.tzinit.org"), and a version-advisory check warns in journald when tzinit advertises a different Octez version than the one installed (octez_node_bootstrap_snapshot_version_check:true)
Optional snapshot upload target for producing your own datadir tarballs via the generated Makefile (octez_node_snapshot_upload_uri:"gs://<bucket>/<prefix>/" — empty disables)
Prometheus metrics exposed by default (octez_node_metrics_port:"9091")
Zcash parameters installed, systemd unit + helper Makefile generated, logs file-sinked under the work dir

Baker: wallet, delegate registration, staking

Wallet provisioning from controller-side files — typically an ansible-vault-decrypted directory (octez_baker_wallet_key_files:[/path/to/secret_keys, ...]), or inline vault-friendly content as a fallback (octez_baker_wallet_key_content:[{name: secret_keys, content: ...}])
A pre-start script registers the delegate and sets consensus and companion keys (relevant since tz4/BLS keys). It runs by default everywhere except mainnet — a deliberate safety default you override per network (octez_baker_run_prestart:true)
Testnet faucet automation: when the balance is below the staking target, the role requests the missing amount from the network faucet — never on mainnet (octez_baker_faucet_request:true, with octez_baker_faucet_request_amount:6000 and a fee reserve octez_baker_keep_for_fees:500)
Staking and delegation tasks are tagged so they can be re-run independently (--tags stake_and_delegate)

Accuser

Installs and operates octez-accuser as a systemd service, waiting for the local node to be up before starting (octez_accuser_node_endpoint:"http://localhost:8732").

DAL node with attester profile wiring

Installs and operates octez-dal-node, renders the attester profile into the config the service actually reads, resolving the baker’s consensus key from the octez-client wallet alias you supply (octez_dal_current_baking_key:"<wallet-alias>")
An empty alias installs the binary + service but skips wallet-dependent init — useful for non-baking DAL nodes (octez_dal_current_baking_key:"", the default)
Metrics exposed for scraping (octez_dal_metrics_port:"11733")

Teztale archiver

Same three download modes as Octez binaries, keyed by its own version pair (teztale_version_type:release, with teztale_version:"teztale-v25.0")
On-disk backup and replay of failed POSTs (new in v0.5.4): during a teztale-server outage the archiver buffers each failed POST on disk instead of dropping it, then replays and purges once the server is back (teztale_archiver_backup_enabled:true, with teztale_archiver_backup_replay:true). Off by default because the underlying --backup-dir/--replay-backups flags require a teztale-archiver built from tezos/tezos master (tezos/tezos!22328) — absent from the teztale-v25.0 release
Feed multiple teztale servers from one archiver (teztale_archiver_extra_feed_urls:["https://..."])
Sender name defaults to the inventory hostname, overridable per deployment (teztale_archiver_sender_name:"{{ inventory_hostname }}")

Supporting services

Status page — a generated HTML report of your whole deployment’s configuration, with an optional top navigation menu (status_page_menu_items:[{label: Grafana, url: ...}]) and optional per-baker deep links into a teztale-dataviz instance (status_page_teztale_dataviz_url:"https://<your-dataviz>/" — empty disables). Since the report describes your fleet, it’s meant to sit behind authentication — the companion oauth2_proxy role deploys a GitLab-SSO auth endpoint you can wire into your web server for that
Netdata — agent install with Octez-aware process grouping, optional Netdata Cloud claiming (claim_token:<token> + claim_rooms:<room>), configurable retention (dbengine_multihost_disk_space:2048 MiB) and local dashboard mode (web_mode:static-threaded)

Quality and versioning

Tested with Molecule: the default scenario boots a systemd-enabled Debian bookworm container, converges artifact_download + node with release binaries, checks idempotence, and verifies the installed binary, unit files, rendered templates, and service enablement. Coverage currently targets the node role, with the remaining roles being added in follow-up work.
Semantic Versioning with vX.Y.Z tags; breaking changes land in major bumps and are recorded in CHANGELOG.rst.
MIT licensed.

Why `infra_nomadic_labs.octez` and not `tezos.octez`?

Top-level Galaxy namespaces are admin-allocated only — there is no self-service way to claim tezos. The collection ships under infra_nomadic_labs (the namespace owned by the maintainer bot account) so the auto-release pipeline can publish end-to-end. If the tezos namespace is ever obtained, a rename is planned as a follow-up release.

Feedback

Feedback and contributions belong on the GitLab repository: tezos-infra / ansible-collection-octez · GitLab — issues can be raised at Work items · tezos-infra / ansible-collection-octez · GitLab

If you’re running Octez on VMs and have been maintaining your own shell scripts or hand-rolled units, give it a try — and if a role is missing a knob you need, that’s exactly the kind of feedback the issue tracker is for.