Quickstart

Get Infrahub up and running in minutes with Docker Compose, then create your first objects.

This quickstart guide will help you get Infrahub running on your local machine using Docker Compose, access the web interface, load an example schema, and create your first infrastructure objects.

For a more comprehensive installation with additional deployment options, see the Installation Guide.

Prerequisites

Before you begin, ensure you have:

• Docker Desktop or Docker Engine (20.10+)
• Docker Compose (2.0+)
• At least 4GB of available RAM
• Internet connectivity to pull Docker images

Get Infrahub running

1. Download the Docker Compose file

   Create a new directory for Infrahub and download the Docker Compose configuration:

   mkdir infrahub-quickstart
   cd infrahub-quickstart
   curl -O https://raw.githubusercontent.com/opsmill/infrahub/stable/docker-compose.yml
   

   This Docker Compose file includes all the necessary services:

   • infrahub-server: The main API server (FastAPI backend)
   • database: Neo4j graph database for storing infrastructure data
   • message-queue: RabbitMQ for asynchronous task processing
   • cache: Redis for caching and session management
   • task-manager: Prefect server for workflow orchestration
   • task-manager-db: PostgreSQL database for Prefect
   • task-worker: Background workers for executing tasks
2. Start Infrahub

   Launch all services with Docker Compose:

   docker compose up -d
   

   Docker will download the required images (this may take a few minutes on first run) and start all services.

3. Verify the services are running

   Check that all containers are healthy:

   docker compose ps
   

   You should see all services in a “running” state with “healthy” status. The initialization process typically takes 30-60 seconds.

4. Access the web interface

   Open your browser and navigate to:

   http://localhost:8000
   

   You’ll be greeted with the Infrahub login page. Use the default credentials:

   • Username: admin
   • Password: infrahub

   Change the default password in production environments by setting INFRAHUB_INITIAL_ADMIN_PASSWORD before starting the services.

Load an example schema

Infrahub starts with no schema by default. Let’s load an example schema that models network devices and sites.

1. Create a schema file

   Create a file named schema.yml with the following content:

   schema.yml

   ---
   version: '1.0'
   nodes:
     - name: Device
       namespace: Infra
       description: "A network device such as a router, switch, or firewall"
       label: "Device"
       default_filter: name__value
       display_label: "{{ name__value }}"
       attributes:
         - name: name
           kind: Text
           unique: true
         - name: description
           kind: Text
           optional: true
         - name: role
           kind: Dropdown
           choices:
             - name: router
               description: "Core or edge router"
               color: "#0099ff"
             - name: switch
               description: "Network switch"
               color: "#00cc66"
             - name: firewall
               description: "Firewall or security appliance"
               color: "#ff6600"
         - name: status
           kind: Dropdown
           choices:
             - name: active
               label: Active
               description: "Operational and in production"
               color: "#009933"
             - name: planned
               label: Planned
               description: "Not yet deployed"
               color: "#cc66ff"
           default_value: "active"
       relationships:
         - name: site
           peer: InfraSite
           optional: false
           cardinality: one
           kind: Attribute
   
     - name: Site
       namespace: Infra
       description: "A physical location or data center"
       label: "Site"
       default_filter: name__value
       display_label: "{{ name__value }}"
       attributes:
         - name: name
           kind: Text
           unique: true
         - name: description
           kind: Text
           optional: true
         - name: facility_id
           label: Facility ID
           kind: Text
           optional: true
   

   This schema defines two node types:

   • InfraDevice: Represents network devices with roles and statuses
   • InfraSite: Represents physical locations
2. Load the schema via API

   Use curl to load the schema into Infrahub:

   curl -X POST http://localhost:8000/api/schema/load \
     -H "Content-Type: application/json" \
     -H "X-INFRAHUB-KEY: 06438eb2-8019-4776-878c-0941b1f1d1ec" \
     -d @schema.yml
   

   The API token 06438eb2-8019-4776-878c-0941b1f1d1ec is the default initial admin token. Change this in production by setting INFRAHUB_INITIAL_ADMIN_TOKEN.

   You should receive a response confirming the schema was loaded successfully.

3. Verify in the UI

   Refresh your browser. You should now see “Device” and “Site” in the left navigation menu under the Objects section.

Create your first objects

Now that the schema is loaded, let’s create some infrastructure objects.

Via Web UI

1. Create a site

   1. Click Site in the left navigation
   2. Click the + Add Site button
   3. Fill in the details:
      • Name: headquarters
      • Description: Main office location
      • Facility ID: HQ-001
   4. Click Save
2. Create a device

   1. Click Device in the left navigation
   2. Click + Add Device
   3. Fill in the details:
      • Name: core-router-01
      • Description: Primary core router
      • Role: router
      • Status: active
      • Site: Select headquarters
   4. Click Save
3. View your objects

   Navigate to the Device or Site list pages to see your newly created objects. Click on any object to view its details and relationships.

Via GraphQL

1. Open the GraphQL sandbox

   Navigate to:

   http://localhost:8000/graphql
   
2. Create a site with a mutation

   Execute this GraphQL mutation:

   mutation CreateSite {
     InfraSiteCreate(
       data: {
         name: { value: "headquarters" }
         description: { value: "Main office location" }
         facility_id: { value: "HQ-001" }
       }
     ) {
       ok
       object {
         id
         name {
           value
         }
       }
     }
   }
   
3. Create a device linked to the site

   First, copy the site ID from the previous response. Then execute:

   mutation CreateDevice($siteId: String!) {
     InfraDeviceCreate(
       data: {
         name: { value: "core-router-01" }
         description: { value: "Primary core router" }
         role: { value: "router" }
         status: { value: "active" }
         site: { id: $siteId }
       }
     ) {
       ok
       object {
         id
         name {
           value
         }
         role {
           value
         }
       }
     }
   }
   

   In the variables panel, provide the site ID:

   {
     "siteId": "<site-id-from-previous-response>"
   }
   
4. Query your objects

   Retrieve all devices with their related sites:

   query GetDevices {
     InfraDevice {
       edges {
         node {
           id
           name {
             value
           }
           role {
             value
           }
           status {
             value
           }
           site {
             node {
               name {
                 value
               }
             }
           }
         }
       }
     }
   }
   

What’s next?

Core Concepts

Learn about schemas, version control, transformations, and more.

Installation Guide

Explore production-ready installation options including Kubernetes.

Create a Schema

Design a custom schema tailored to your infrastructure.

GraphQL API

Deep dive into querying and mutating data with GraphQL.