Building & contributing to netbox-opennms-plugin

One installable plugin package (netbox_opennms/) plus the Docker test harness, the quickstart demo, and CI. The package is layered bottom-up — the OpenNMS port at the base, pure translation in the middle, UI on top.

netbox-opennms-plugin/
├── netbox_opennms/            # the plugin package
│   ├── __init__.py            #   PluginConfig + single-sourced __version__
│   ├── client/                #   OpenNMS REST client + discovery (the only I/O port)
│   ├── catalog.py             #   cached detector/policy/asset catalog (live + overlay)
│   ├── presets.py             #   curated preset overlay (labels/defaults)
│   ├── models.py  choices.py  #   Requisition, detectors, policies, overrides, mappings
│   ├── migrations/            #   schema migrations
│   ├── membership.py          #   filter → members; conflict resolution
│   ├── filtersets.py  derivation.py  validation.py
│   ├── enrichment.py          #   NetBox attribute → asset/metadata resolver
│   ├── translation/           #   pure render: requisition + foreign-source XML
│   ├── jobs.py  dryrun.py  signals.py   # sync/remove jobs, dry-run diff, reconciler
│   ├── forms.py  views.py  tables.py  navigation.py  urls.py  api/  templates/
│   └── tests/                 #   unit suite + live-OpenNMS integration + spike
├── compose.yml                # test stack (Postgres + Redis + NetBox test runner)
├── compose.integration.yml    # overlay: disposable OpenNMS Horizon 36
├── Makefile                   # every CI + dev command (lint/test/build/integration)
├── quickstart/                # runnable demo: NetBox UI + worker + OpenNMS + seed
├── docs/                      # this page + screenshots
└── .github/workflows/ci.yml   # lint · unit · gated live integration

The version is single-sourced, main requires signed commits, and a release is a signed tag plus a GitHub release. PyPI publishing is a planned fast-follow.

1. Bump the single source of truth — __version__ in netbox_opennms/__init__.py (pyproject reads it dynamically) — on a branch, and open a PR.
2. CI must be green (make verify + wheel build). Merge via squash or rebase.
3. Tag the release commit and push, then cut the GitHub release:

git tag -a v0.0.1 -m "netbox-opennms-plugin 0.0.1 — first public release"
git push origin v0.0.1
gh release create v0.0.1 --verify-tag --notes-file NOTES.md

Issues and pull requests are welcome. One focused change per PR; CI runs the same Makefile targets you run locally, so there are no surprises.

• Branch per change off main; open a PR.
• Conventional Commits — feat / fix / docs / refactor / test / chore / ci, with a scope where it helps.
• Sign your commits — DCO sign-off and a cryptographic signature: git commit -s with commit.gpgsign true.
• SPDX header on every new/edited source file (SPDX-License-Identifier: MIT).
• Green before you push — make verify (ruff + the full unit suite) must pass; CI enforces it.

Python 3.12+. Install editable for development, or build the distributables.

# editable install into your NetBox virtualenv
pip install -e .

# install a tagged release straight from Git (until PyPI lands)
pip install "git+https://github.com/no42-org/netbox-opennms-plugin@v0.0.1"

# build the wheel + sdist into dist/ (also asserts the wheel ships its templates)
make build

No local NetBox install needed. The Makefile runs everything in a throwaway Postgres/Redis/NetBox container, so local and CI use the identical commands.

The unit suite never depends on OpenNMS. The live round-trip boots a disposable OpenNMS Horizon 36 and drives real requisition imports — it is gated on OPENNMS_LIVE_URL, runs nightly in CI, and on demand.

# boot a throwaway OpenNMS Horizon 36 and run the live round-trip
make integration

# the exploratory spike (captures real /foreignSourcesConfig payloads)
make integration-spike

Under the hood, compose.integration.yml overlays a disposable OpenNMS onto the test stack and points the test container at it via OPENNMS_LIVE_URL. Without that variable set, the live tests skip, so make verify stays green with no OpenNMS around.

To click through a real feature — author a Requisition, add detectors/policies, dry-run, and Sync a node into OpenNMS — bring up the seeded quickstart stack: NetBox (UI + worker) and a disposable OpenNMS Horizon 36. It lives in quickstart/.

Run it

From the repo's quickstart/ directory:

# NetBox UI + background worker only (point the plugin at your own OpenNMS)
docker compose up -d

# …or the full self-contained loop incl. a disposable OpenNMS Horizon 36
docker compose --profile opennms up -d

First boot runs migrations, creates the superuser, and initializes OpenNMS's schema, so allow a few minutes (docker compose ps until healthy; docker compose logs -f netbox to watch).

Seed test data

Load sample Devices, VMs, and Requisitions so there's something to sync immediately (idempotent — everything is get_or_create'd):

./seed.sh
# …or:  docker compose exec -T netbox \
#         /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py shell < seed.py

It builds 3 sites × a few roles, devices with multiple interfaces + additional IPs, VMs on a site-scoped cluster, and 5 Requisitions (each a site+role filter with inline detectors and declared services) — including a multi-node Foreign Source mixing devices and VMs, a requisition with an OpenNMS-unknown location (trips the no-Minion warning), per-object overrides, and one unmonitored object. Edit seed.py to taste.

Do a sync (Web UI)

Open http://localhost:8000/ (admin / admin) → Plugins → NetBox OpenNMS:

1. (or run ./seed.sh and skip to step 4) Create the prerequisites (a Site, Device Role, Manufacturer + Device Type, then a Device with a primary IP).
2. Requisitions → Add: name it (e.g. core-switches), set a filter that selects your device — e.g. {"role": ["<role-slug>"]} or Import from Saved Filter — and use the panel Add buttons to attach detectors, policies, asset mappings, and metadata.
3. Dry run to preview, per node, exactly what a Sync would push.
4. Sync to OpenNMS — the OpenNMS Sync Status panel shows submitted → succeeded-accepted (the worker runs the job); the node appears in OpenNMS under the Requisition's Foreign Source name.

Point at your own OpenNMS

Edit configuration/plugins.py — set opennms_url, opennms_username, opennms_password — then docker compose up -d (no --profile opennms). The plugin needs an account that can read/write requisitions and trigger imports.

How it's wired

• The plugin is mounted from the repo root (../ → /source) on PYTHONPATH — no rebuild on code changes; restart the netbox + netbox-worker containers to pick them up.
• netbox-worker runs manage.py rqworker — required, because Sync/Remove/Move run as background jobs.
• configuration/plugins.py is mounted at /etc/netbox/config/plugins.py to set PLUGINS + PLUGINS_CONFIG.

Tear down

docker compose --profile opennms down -v      # -v also drops the data volumes