# Deploying Octez stack with Ansible: the octez collection

**URL:** https://forum.tezosagora.org/t/deploying-octez-stack-with-ansible-the-octez-collection/7152
**Category:** Project Updates
**Tags:** infrastructure
**Created:** [August 3, 2026, 4:44pm UTC](https://forum.tezosagora.org/t/deploying-octez-stack-with-ansible-the-octez-collection/7152 "2026-08-03T16:44:00Z")
**Posts on this page:** 1
**Page:** 1

<div class="post-metadata">

### Author: ![cmehat](https://forum.tezosagora.org/user_avatar/forum.tezosagora.org/cmehat/32/2712_2.png) [@cmehat](https://forum.tezosagora.org/u/cmehat)
#### Post date: [August 3, 2026, 4:44pm UTC](https://forum.tezosagora.org/t/deploying-octez-stack-with-ansible-the-octez-collection/7152/1 "2026-08-03T16:44:00Z")

</div>

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](https://gitlab.com/tezos-infra/ansible-collection-octez)
- **Ansible Galaxy:** [Ansible Galaxy](https://galaxy.ansible.com/ui/repo/published/infra_nomadic_labs/octez/)

Install from Galaxy:

```sh
ansible-galaxy collection install infra_nomadic_labs.octez

```

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

```yaml
# 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:

```yaml
- 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](http://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](https://gitlab.com/tezos-infra/ansible-collection-octez) — issues can be raised at [Work items · tezos-infra / ansible-collection-octez · GitLab](https://gitlab.com/tezos-infra/ansible-collection-octez/-/work_items)

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.