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.
Verification

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

Log in​

Infrahub creates an administrator account the first time it starts. Until you log in, you can view data but not change it, so the WebUI steps later in this tutorial need you to be logged in.

Default credentials
  • Username: admin
  • Password: infrahub

After you log in, the bottom-left corner shows your account instead of Log in.

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 OpsMill.

  1. Download the base schema collection from the Infrahub Marketplace:
infrahubctl marketplace get infrahub/base-schemas --collection

This downloads the schema YAML to ./schemas/.

  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.

info

Instead of navigating the menu, press Cmd+K (macOS) or Ctrl+K (Windows and Linux) and type a name to jump straight to any object, schema, or page. See Search anywhere.

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