Skip to main content

How to install the demo environment

This guide walks you through installing and setting up the Infrahub DC fabric demo environment on your local machine or server.

What you'll achieve​

By following this guide, you'll have a fully functional Infrahub instance with the demo DC fabric environment ready to use. This includes:

  • A running Infrahub instance with Docker Compose
  • Python dependencies installed via Poetry
  • Environment variables configured for the demo
  • Schema and initial data loaded into Infrahub

Prerequisites​

Before starting, ensure you have the following installed on your system:

Required tools​

  • Docker and Docker Compose - For running Infrahub services

  • Python 3.10, 3.11, or 3.12 - Required for the Infrahub SDK and demo scripts

    • Python 3.13+ is not currently supported
    • Verify with: python --version or python3 --version

  • Poetry - Python dependency management

  • Git - For cloning the repository

    • Verify with: git --version

Optional tools​

  • Containerlab - If you plan to deploy and test the generated configurations on virtual network devices

Step 1: Clone the repository​

Clone the demo repository to your local machine:

git clone https://github.com/opsmill/infrahub-demo-dc-fabric.git
cd infrahub-demo-dc-fabric

Step 2: Set environment variables​

Configure the required environment variables for the demo:

export INFRAHUB_ADDRESS="http://localhost:8000"
export INFRAHUB_API_TOKEN="06438eb2-8019-4776-878c-0941b1f1d1ec"

If you plan to use Containerlab for lab testing, also set:

export CEOS_DOCKER_IMAGE="registry.opsmill.io/external/ceos-image:4.29.0.2F"
export LINUX_HOST_DOCKER_IMAGE="registry.opsmill.io/external/alpine-host:v3.1.1"
tip

Add these exports to your shell profile (.bashrc, .zshrc, etc.) to persist them across sessions.

Step 3: Install Python dependencies​

Use Poetry to install the required Python packages:

poetry install

This command:

  • Creates a virtual environment for the project
  • Installs the Infrahub SDK and all dependencies
  • Installs development tools (ruff, yamllint, mypy, pytest)
info

The --no-root flag is not needed as this project uses package-mode = false in pyproject.toml.

Step 4: start Infrahub​

Start the Infrahub services using Docker Compose:

poetry run invoke start

This command:

  • Downloads the Infrahub Docker Compose configuration
  • Starts all required services (API, Git agent, database, message queue)
  • Runs services in detached mode (background)

Wait for all services to be healthy. You can check the status with:

docker compose ps

The Infrahub UI should be accessible at http://localhost:8000.

warning

The first time you run this command, it may take several minutes to download Docker images.

Step 5: Load the schema​

Load the data model schema into Infrahub:

poetry run invoke load-schema

This command loads all schema files from the schemas/ directory, defining:

  • Device types and interfaces
  • IP address management (IPAM) objects
  • Network topologies
  • Security policies
  • Organizations and locations

The command waits up to 30 seconds for the schema to be fully processed.

Step 6: Load initial data​

Populate Infrahub with the demo data:

poetry run invoke load-data

This runs the bootstrap scripts in sequence:

  1. create_basic.py - Creates accounts, tags, organizations, and device types
  2. create_location.py - Creates locations, VLANs, and IP prefixes
  3. create_topology.py - Creates topology definitions and topology elements
  4. create_security_nodes.py - Creates security policies, rules, and objects

Validation​

Verify the installation was successful:

Check Infrahub is running​

  1. Open http://localhost:8000 in your browser
  2. Log in with the default credentials (check Infrahub documentation for defaults)
  3. Navigate to Unified Storage > Schemas to see the loaded schema

Troubleshooting​

Docker services won't start​

  • Ensure Docker Desktop is running
  • Check if ports 8000, 5432, or other required ports are already in use
  • Review Docker logs: docker compose logs

Poetry install fails​

  • Ensure you're using Python 3.10-3.12 (not 3.13+)
  • Try removing the poetry.lock file and running poetry install again
  • Check that Poetry is using the correct Python version: poetry env info

Permission denied errors with Containerlab​

  • Containerlab requires sudo privileges
  • Ensure your user is in the docker group: sudo usermod -aG docker $USER

Next steps​

With the environment installed, you can:

  • Follow the user walkthrough to create your first network service
  • Explore the concepts to understand how Infrahub manages infrastructure data
  • Read the developer guide to understand how the demo works under the hood