Skip to main content

How to Install the Service Catalog Demo

This guide walks you through installing the Service Catalog demo, which demonstrates how to build a self-service portal on top of Infrahub's source of truth system. By the end of this guide, you'll have a working environment where users can request network services through a web interface.

Need help or have questions? Join our Discord community for support!https://discord.gg/opsmill

What you'll achieve​

After completing this installation:

  • Infrahub instance running with network infrastructure data
  • Service Catalog portal accessible for requesting services
  • Demo data loaded including locations, devices, and network resources
  • Git integration configured for infrastructure as code workflows
  • Semaphore automation ready to deploy configurations to network devices

Prerequisites​

Before you get started, make sure you have these tools installed:

Required software​

  • 🐳 Docker: Container runtime for running Infrahub and its dependencies

    • Docker Desktop for local development
    • Or Docker Engine on a Linux VM for server deployments
    • Minimum 4GB RAM allocated to Docker

  • 🐍 uv: Fast Python package and project manager

    • Install via the official installation guide
    • Used to manage Python packages and virtual environments
    • Version 0.4.0 or higher recommended

System requirements​

  • Operating System: macOS, Linux, or Windows with WSL2
  • Memory: At least 8GB RAM (16GB recommended)
  • Storage: 10GB free disk space
  • Network: Internet connection for downloading dependencies

Installation steps​

Step 1: Clone the repository​

First, download the demo code from GitHub. This repository contains all the necessary configuration files, schemas, and demo data.

git clone https://github.com/opsmill/infrahub-demo-service-catalog.git
cd infrahub-demo-service-catalog
What's in the Repository?

The repository includes:

  • Infrahub schemas defining the data models for network infrastructure
  • Demo data with sample locations, devices, and network resources
  • Service Catalog application built with Streamlit
  • Docker configuration for running all components

Step 2: Configure environment variables​

Set up the connection details for Infrahub. These variables tell the Service Catalog application how to communicate with the Infrahub API.

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

Understanding the variables​

  • INFRAHUB_ADDRESS: The URL where Infrahub's API is accessible

    • Default uses localhost:8000 for local development
    • Change this if running Infrahub on a different host or port

  • INFRAHUB_API_TOKEN: Authentication token for API access

    • The demo uses a pre-configured token for convenience
    • In production, use secure token generation and storage

Step 3: Install Python dependencies​

Use uv to create a virtual environment and install all required Python packages.

uv sync

This command:

  • Creates an isolated Python virtual environment
  • Installs the Infrahub SDK for API interactions
  • Installs Streamlit for the web portal interface
  • Sets up development tools (pytest, ruff, mypy)
First time using uv?

uv automatically manages virtual environments. All subsequent commands should be run with uv run prefix to ensure they use the correct environment.

Step 4: Start the application stack​

Launch Infrahub and the Service Catalog using Docker Compose. This single command starts multiple services.

uv run invoke start
Why Use Invoke?

The invoke start command is a wrapper that:

  • Ensures the correct Docker Compose configuration is used
  • Mounts the service_catalog module into the Infrahub container
  • Starts Infrahub, the Streamlit application, and Semaphore
  • Sets up networking between containers

What gets started​

This command launches:

  • Infrahub Core: The main application server (port 8000)
  • PostgreSQL: Database for storing infrastructure data
  • Redis: Cache and message broker
  • RabbitMQ: Task queue for asynchronous operations
  • Service Catalog: Streamlit web portal (port 8501)
  • Semaphore: Ansible automation UI (port 3000)

Step 5: Initialize the demo environment​

Once Infrahub is up and running, initialize the demo by loading the repository, permissions, and seeding Semaphore.

uv run invoke init

This single command performs three things:

  1. Seeds Semaphore with the project, SSH key, repository, inventory, environment, and task template (idempotent — safe to run multiple times)
  2. Loads the repository configuration from repository.yaml into Infrahub — a read-write CoreRepository that references the local checkout mounted at /upstream in the container
  3. Loads permissions from permissions.yml, creating an operator account (john / infrahub) with permissions to manage repositories, merge branches, and review proposed changes

What the repository provides​

Once Infrahub imports the repository, it picks up:

  • Generator Scripts: Python code that automates service provisioning
  • Configuration Templates: Jinja2 templates for device configurations
  • Schema: Data models for DCIM, IPAM, services, and locations
  • Objects and data: Demo infrastructure loaded from YAML fixtures
  • Menu: Custom navigation structure for the Infrahub UI
Understanding the Data Model

The repository imports:

  • Locations: Sites in Paris, Brussels, New York, and Dallas
  • Devices: Core switches and edge routers at each site
  • Providers: Transit and peering providers (Cogent, Zayo, Colt, Lumen, Equinix)
  • Network Resources: VLAN pools, IP prefix pools, interface profiles
  • Templates: Device configurations and service definitions

The schema uses a hierarchical structure:

  • Locations contain devices
  • Devices have interfaces and connections
  • Services allocate resources from pools
  • Everything is version-controlled and auditable

Verify your installation​

Confirm everything is working by accessing both interfaces:

Infrahub web UI​

  • URL: http://localhost:8000
  • Admin account: admin / infrahub
  • Operator account: john / infrahub (limited permissions)
  • What to Check:
    • Navigate to the Schema page to see loaded models
    • Check the Objects page to verify demo data is present
    • Confirm the repository appears under Repositories
    • Log in as john to verify operator-level access works

Service catalog portal​

  • URL: http://localhost:8501
  • What to Check:
    • Home page displays available services
    • Service request forms are accessible
    • No connection errors appear

Semaphore automation UI​

  • URL: http://localhost:3000
  • Username: admin
  • Password: semaphore
  • What to Check:
    • Login page loads successfully
    • The "Service Catalog" project is visible (created by invoke init)
    • The "Deploy" task template and "Infrahub" inventory are configured

Troubleshooting common issues​

Services won't start​

  • Ensure Docker is running and has sufficient resources
  • Check for port conflicts (3000, 8000, 8501, 5432, 6379)
  • Run uv run invoke destroy then uv run invoke start to reset

Schema load fails​

  • Wait for Infrahub to fully start (check logs with docker compose logs infrahub)
  • Retry the schema load command after 30 seconds

Can't access web interfaces​

  • Verify environment variables are set correctly
  • Check firewall rules if running on a remote server
  • Ensure all containers are running: docker compose ps

Next steps​

Now that your environment is running:

  1. For Users: Follow the user walkthrough to learn how to request services
  2. For Developers: Check the developer walkthrough to understand the architecture
  3. Explore Further: Browse the Infrahub UI to understand the data model and relationships