Skip to main content

Quick start

This page gets you from clone to a running demo in about 10 minutes. For an overview of what invoke init creates, see the landing page.

Prerequisites​

  • Docker / Docker Compose
  • Python 3.10+
  • uv
  • (Optional) containerlab >= 0.50 — only for invoke lab.deploy, which has much heavier requirements than the rest of the demo: a Linux host and 32 GB+ RAM for the default dataset's 12 cEOS routers. See Containerlab prerequisites. Everything else on this page runs fine on a laptop.
  • (Optional) pnpm — only needed for uv run invoke docs, which builds the Docusaurus site locally

1. Clone and install​

git clone https://github.com/opsmill/infrahub-demo-sp.git
cd infrahub-demo-sp
cp .env.example .env
set -a; source .env; set +a
uv sync

Open .env and review the values — see Configuration below for what each variable does. The defaults are fine for a local demo; you typically only edit INFRAHUB_SERVICE_CATALOG (to enable the Streamlit sidecar) and INFRAHUB_DATASET (to switch tenant theme).

set -a is required, and re-running it is required in every new shell: .env holds quoted assignments, so a bare source .env leaves them as shell variables that invoke and infrahubctl never see, and the next step fails at "Loading schemas" with Authentication is required.

2. Start Infrahub and bootstrap data​

uv run invoke init

This destroys any prior state, starts the containers, loads the schemas, the menu, all bootstrap objects (resource pools plus the selected dataset — its backbone, tenants, and services), and generates schema protocol bindings. The backbone ships inside the dataset: the default financial dataset loads 8 Arista cEOS PEs (pe-01…pe-08) in a partial mesh plus 4 pre-provisioned Arista cEOS CE routers on the two hub PEs, while isp loads 4 multi-vendor PEs in a full mesh.

Wait ~30 s after the containers come up before bootstrap runs.

3. Open the Infrahub UI​

Visit http://localhost:8000 — log in with admin / infrahub. The sidebar menu shows Service Catalog → L3 VPNs, Topology → MPLS Backbones, and MPLS (ISIS / LDP / MP-BGP processes).

4. Start the Streamlit Service Catalog​

Set INFRAHUB_SERVICE_CATALOG="true" in .env, then run:

uv run invoke start

Every invoke start / invoke init will now also start the Streamlit sidecar, from the published image. Visit http://localhost:8501. Create your first L3VPN.

Container images​

invoke start pulls the Service Catalog and the Batfish runner from the OpsMill registry. Each image is published for linux/amd64 and linux/arm64 under these tags:

TagPoints to
mainThe latest build of the main branch. CI also rebuilds it weekly to pick up base image fixes.
sha-<commit>One exact commit. It never moves, so pin it in a deployment.

To run the Service Catalog without Docker Compose, point it at an Infrahub instance:

docker run --rm -p 8501:8501 \
  -e INFRAHUB_ADDRESS=http://host.docker.internal:8000 \
  -e INFRAHUB_API_TOKEN=<your-api-token> \
  registry.opsmill.io/opsmill/infrahub-demo-sp-streamlit:main

The container listens on port 8501. Set STREAMLIT_SERVER_PORT to use another port.

CI signs every image with Cosign and attaches a software bill of materials to it. To verify a signature:

cosign verify \
  --certificate-identity-regexp "^https://github.com/opsmill/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  registry.opsmill.io/opsmill/infrahub-demo-sp-streamlit:main

Build the images from your checkout​

To change service_catalog/ or batfish_runner/, build the images locally instead of pulling them. Either set INFRAHUB_SERVICE_CATALOG_BUILD="true" in .env, or run:

uv run invoke start --build

This builds both images from the repository and mounts their sources into the containers, so edits show up without a rebuild.

The Service Catalog also exposes a second wizard — Create SD-WAN service — for provisioning Cisco Viptela or Versa Networks SD-WAN overlays. The flow mirrors Create L3VPN: pick vendor and topology, list the sites, submit. See services/sdwan for the lifecycle, vendor differences, and known gaps.

5. (Optional) Run Batfish validation​

Under the sidebar Validation → Batfish Check the catalog runs BatfishBackboneCheck against the rendered MPLS backbone configs and shows findings bucketed by severity. Each query (parse status, undefined references, BGP session compatibility, IS-IS adjacency mesh) progresses with its own status indicator so a slow Batfish init isn't a blank screen.

The Batfish sidecar is enabled by default in docker-compose.override.yml and started by invoke start. You can also run the same check from the command line:

uv run invoke batfish

See validation/batfish for what each finding means and how severity is tiered.

6. Add a PE router as a proposed change​

uv run invoke demo-add-device

This adds a PE router to the backbone the way the catalog's Add PE page does. It opens a branch, creates the router with its loopback, core links, IS-IS, LDP and iBGP sessions to every other PE, and opens a proposed change into main. On the default financial dataset the new router is pe-09, linked to pe-01 and pe-02. The command ends with a link to the proposed change, where the checks run and the configuration diffs show, and with the command that boots the change in the lab (step 7).

See Add a PE router for the options and what each step creates.

7. (Optional) Bring up the containerlab​

uv run invoke lab.deploy                     # the backbone on main
uv run invoke lab.deploy --branch <branch>   # a proposed change, before merging

See lab/containerlab.

Configuration​

All configurable behaviour is driven by environment variables in .env (loaded with set -a; source .env; set +a before any uv run invoke command). uv run invoke info prints the resolved values.

VariableDefaultEffect
INFRAHUB_ADDRESShttp://localhost:8000Where the SDK / Streamlit catalog reach the server
INFRAHUB_API_TOKENdemo tokenAuthentication. Rotate before any non-local use
INFRAHUB_UI_URLhttp://localhost:8000Used by the Streamlit catalog for "open in Infrahub" links
INFRAHUB_GIT_LOCALfalsetrue registers a CoreRepository pointed at the bind-mounted /upstream (no GitHub clone needed). false registers a CoreReadOnlyRepository against the public GitHub repository
INFRAHUB_SERVICE_CATALOGfalsetrue starts the Streamlit sidecar, from the published image, on every invoke start / invoke init
INFRAHUB_SERVICE_CATALOG_BUILDfalsetrue builds the Streamlit and Batfish runner images from this checkout instead of pulling them, and mounts their sources. invoke start --build does the same for one run
STREAMLIT_IMAGEregistry.opsmill.io/opsmill/infrahub-demo-sp-streamlit:mainImage the Streamlit sidecar runs
BATFISH_RUNNER_IMAGEregistry.opsmill.io/opsmill/infrahub-demo-sp-batfish-runner:mainImage the Batfish runner runs
INFRAHUB_DATASETfinancialSelects a dataset overlay — one subdirectory of objects/datasets/. Each dataset ships its own backbone plus its tenants and services. financial (internal bank): 8 Arista cEOS PEs (pe-01…pe-08) in a partial mesh, 8 division tenants, trading-floor-vpn. isp (Lumina Networks pan-European ISP): 4 multi-vendor PEs in a full mesh, 8 customer tenants, kestrel-bank-mpls
INFRAHUB_ENTERPRISEfalsetrue streams the Enterprise edition compose file from https://infrahub.opsmill.io/enterprise/<INFRAHUB_VERSION> instead of the Community one. Requires an Enterprise license / pull credentials
INFRAHUB_VERSIONstableCompose file version tag pulled from infrahub.opsmill.io (use latest, stable, or a specific release like 1.4.0)
INFRAHUB_PORT8000Override the Infrahub server port
PREFECT_PORT4200Override the Prefect task-manager port
STREAMLIT_PORT8501Override the Streamlit catalog port

To switch dataset:

# in .env
INFRAHUB_DATASET="isp"

…then uv run invoke init to wipe and reload from the new dataset.

Troubleshooting​

See troubleshooting.