Skip to main content

Quick Start

In this tutorial, you will set up a local Infrahub instance on your machine, load a schema that defines your data model, create infrastructure objects, and explore branching. By the end, you will have a working environment with real data you can interact with.

This quick start serves a dual purpose: it teaches you the fundamentals of Infrahub — schemas, infrahubctl, and branching — and it sets up a local development environment that you can continue building on as you go deeper.

Time: ~30 minutes

What you will build: A running Infrahub instance with a network location data model, location data, and a branch with proposed changes.

note

Running Infrahub locally with Docker is the most convenient setup for development and experimentation, but it requires a machine with adequate resources. See hardware requirements for details. If you prefer a lighter option, try the Infrahub Sandbox or the Getting Started Lab instead.

Prerequisites:

  • Docker installed and running (Docker Desktop or OrbStack)
  • uv (Python package manager)
  • Python 3.10+

Create a project​

Copier is a project scaffolding tool. Use it to create a new Infrahub project from the official template, which includes the standard file structure, task definitions, and a schemas/ folder:

  1. Run the following command to create a new project directory:
uv tool run --from 'copier' copier copy https://github.com/opsmill/infrahub-template infrahub-automation

If you are unsure about the options, accept the default values for all prompts by pressing Y.

  1. Navigate to the project directory:
cd infrahub-automation
  1. Open the project in your IDE. If you have Visual Studio Code installed, you can run:
code .
Verification

Run ls in the project directory. You should see files including pyproject.toml, tasks.py, and a schemas/ folder.

Start Infrahub​

The project template includes Invoke tasks that wrap Docker Compose commands.

  1. Start all Infrahub services with a single command:
uv run invoke start

The first run takes a few minutes while Docker downloads the container images.

  1. Open your browser and go to http://localhost:8000.

  2. Log in from the bottom-left corner using the default credentials:

    • Username: admin
    • Password: infrahub
Verification

You should see the Infrahub web interface with a navigation menu on the left side.

Load a schema​

A schema defines the structure of your infrastructure data in Infrahub — the types of objects, their attributes, and how they relate to each other. Learn more about schemas.

Rather than writing a schema from scratch, use the Infrahub Marketplace, a catalog of reusable schemas for common infrastructure domains maintained by the community and OpsMill.

  1. Browse marketplace.infrahub.app and identify the schema you need (for example, opsmill/dcim).

  2. Fetch the schema to your project:

infrahubctl marketplace get opsmill/dcim

This downloads the schema YAML to ./schemas/.

info

The Marketplace organizes schemas into base schemas (core definitions) and extensions that build on top of a base. You need to load the base before loading extensions. Browse the Marketplace to discover what is available and check each schema's dependencies.

  1. Load the schema into your project:
infrahubctl schema load schemas/
Verification

Go back to http://localhost:8000 and refresh the page. The left-hand menu should now display new items including location types like Country and Site.

Create your first data​

There are multiple ways to create data in Infrahub — the WebUI, APIs, Python SDK, and more. For development purposes, it's often easiest to create YAML files and load them with infrahubctl.

  1. Create a file called countries.yml in the objects/ folder with the following content:
---
apiVersion: infrahub.app/v1
kind: Object
spec:
  kind: LocationCountry
  data:
    - name: United States
      shortname: US
      description: US operations
      children:
        kind: LocationMetro
        data:
          - name: Denver
            shortname: DEN
    - name: France
      shortname: FR
      description: EU operations
      children:
        kind: LocationMetro
        data:
          - name: Paris
            shortname: PAR
  1. Load the data into Infrahub:
uv run infrahubctl object load objects/countries.yml
Verification

Go to http://localhost:8000 and navigate to the Country list in the left-hand menu. You should see United States and France. Click on United States to view its details.

Explore branching​

Branches in Infrahub work like Git branches — they let you stage changes in isolation without affecting the main dataset. This is one of Infrahub's most powerful features: you can propose, review, and test data changes before merging them. Learn more about branching.

  1. Create a branch called add-locations:
uv run infrahubctl branch create add-locations
  1. Add sites in the add-locations branch:
  1. Create a file called sites.yml in the objects/ folder:
---
apiVersion: infrahub.app/v1
kind: Object
spec:
  kind: LocationSite
  data:
    - name: Denver DC1
      shortname: DEN1
      description: Primary US data center
      parent: DEN
    - name: Paris DC1
      shortname: PAR1
      description: Primary EU data center
      parent: PAR
  1. Load the sites into the add-locations branch:
uv run infrahubctl object load objects/sites.yml --branch add-locations

Notice the --branch flag — this targets the branch instead of main.

Verification

Go to http://localhost:8000. In the top-left corner, use the branch selector to switch to the add-locations branch. Navigate to the Site list in the left-hand menu. You should see Denver DC1 and Paris DC1.

Switch back to the main branch. The sites are not visible because they only exist in the add-locations branch.

Next steps​

You now have a working Infrahub development environment. You know how to:

  • Start a local Infrahub instance
  • Load a schema to define your data model
  • Create infrastructure objects from YAML files
  • Use branches to isolate changes from the main dataset

The Next Steps guide walks you through turning this local setup into a proof of concept for your organization — from designing your own schema to generating artifacts and deploying to a shared environment.

Next Steps./next-steps