ansible: rewrite netbox role to match live netbox.vntx.net (bare-metal install)

The previous role was netbox-community/netbox-docker (compose-based) but
the live host runs the upstream tarball install directly: system Postgres
17, system Redis 8, gunicorn under systemd, and Caddy reverse-proxy.
Re-running the old role would have torn the working install down.

This rewrite mirrors what's actually deployed:

- defaults: NetBox 4.6.0, /opt/netbox layout, gunicorn 5w/3t/120s, all
  configuration.py knobs exposed as ansible vars.
- tasks: install OS deps, ensure netbox user, create Postgres role + db,
  download + extract release tarball, run upgrade.sh, render
  configuration.py / gunicorn.py / systemd units, enable services.
- templates: configuration.py.j2 covers the same keys the live file sets;
  netbox.service / netbox-rq.service are byte-equivalent to the live
  units (modulo paths driven by the install-dir var).
- caddy role gets a per-host Caddyfile-netbox.vntx.net.j2 mirroring the
  live vhost (25MB body limit, /static/* file_server, reverse_proxy to
  127.0.0.1:8001).
- inventory: new netbox_servers group; netbox.vntx.net added to
  caddy_servers so the per-host Caddyfile is wired up.
- host_vars/netbox.vntx.net.yml: secrets reference vault_* vars; role
  refuses to render config.py until they're set.

Operator action: create host_vars/netbox.vntx.net/vault.yml with
netbox_secret_key, netbox_db_password, and netbox_api_token_peppers
(value visible via `sudo cat /opt/netbox/netbox/netbox/configuration.py`
on the live host). See roles/netbox/README.md.

2026-05-08 12:17:30 -05:00

1.7 KiB

Raw Permalink Blame History

netbox role

Bare-metal NetBox install matching the live netbox.vntx.net layout:

Debian 13 (trixie) host
System PostgreSQL 17 + Redis 8
NetBox release tarball extracted under /opt/netbox-<version>, symlinked to /opt/netbox
Python venv managed by NetBox's bundled upgrade.sh
gunicorn bound to 127.0.0.1:8001 under systemd (netbox.service)
Background worker under netbox-rq.service
Reverse proxy via the repo's existing caddy role using the per-host template roles/caddy/templates/Caddyfile-netbox.vntx.net.j2

Required vault variables

The role refuses to render config without these. Put them in host_vars/netbox.vntx.net/vault.yml (encrypted with ansible-vault) or any equivalent secrets store:

netbox_secret_key: "<>= 50 random chars>"        # generate with /opt/netbox/netbox/generate_secret_key.py
netbox_db_password: "<postgres password>"
netbox_api_token_peppers:                         # optional, only if rotating peppers
  1: "<32+ random hex chars>"

Idempotency

Re-running the playbook against a host already at the target version is a no-op except for config rendering. To upgrade:

Bump netbox_version in defaults or host_vars.
Run the play. The role downloads the new tarball, re-points the /opt/netbox symlink, runs upgrade.sh (which handles venv + migrations
- collectstatic), and bounces the systemd units.

What the role does NOT manage

The data inside NetBox (sites, devices, IPs, etc.). Use the netbox.netbox Ansible collection or NetBox's import APIs for that.
Postgres performance tuning beyond defaults (shared_buffers, etc.).
Off-host backups of the Postgres DB. Add a separate cron / restic job.

1.7 KiB Raw Permalink Blame History

netbox role

Required vault variables

Idempotency

What the role does NOT manage

1.7 KiB

Raw Permalink Blame History