Installation

This guide covers multiple installation methods for Infrahub, from quick local deployments to production-ready Kubernetes clusters.

For a faster getting-started experience, see the Quickstart Guide.

Prerequisites

System requirements

Minimum requirements for running Infrahub:

CPU: 2 cores (4+ recommended for production)
RAM: 4GB minimum (8GB+ recommended for production)
Storage: 20GB available disk space
OS: Linux, macOS, or Windows with WSL2

Software dependencies

Docker Compose
Kubernetes

Docker Desktop 4.0+ or Docker Engine 20.10+
Docker Compose 2.0+
curl (for downloading files)

Installation methods

Docker Compose
Kubernetes
Development (Invoke)

Docker Compose is the recommended method for development, testing, and small production deployments.

Quick installation

Create a directory for Infrahub

mkdir infrahub
cd infrahub

Download the Docker Compose file

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

Configure environment variables (optional)

Create a .env file to customize your deployment:

.env

# Version
VERSION=1.7.6

# Initial credentials
INFRAHUB_INITIAL_ADMIN_PASSWORD=your-secure-password
INFRAHUB_INITIAL_ADMIN_TOKEN=your-admin-token
INFRAHUB_INITIAL_AGENT_TOKEN=your-agent-token

# Security
INFRAHUB_SECURITY_SECRET_KEY=your-secret-key

# Database
INFRAHUB_DB_USERNAME=neo4j
INFRAHUB_DB_PASSWORD=your-db-password

# Broker
INFRAHUB_BROKER_USERNAME=infrahub
INFRAHUB_BROKER_PASSWORD=your-broker-password

# Production mode
INFRAHUB_PRODUCTION=true
INFRAHUB_ALLOW_ANONYMOUS_ACCESS=false

Always change default passwords and tokens in production environments.

Start Infrahub

docker compose up -d

This command starts all required services:

infrahub-server: FastAPI backend serving the GraphQL API and REST endpoints
database: Neo4j 2025.10.1 graph database
message-queue: RabbitMQ 4.2.1 for asynchronous messaging
cache: Redis 8.4.0 for caching and session storage
task-manager: Prefect server for workflow orchestration
task-manager-db: PostgreSQL 18 for Prefect metadata
task-worker: Background workers (2 replicas by default)

Verify the installation

Check service health:

docker compose ps

All services should show as “healthy”. View logs:

docker compose logs -f infrahub-server

Access Infrahub

Open your browser to:

http://localhost:8000

Username: admin
Password: infrahub (or your custom password from .env)

Service architecture

The Docker Compose deployment includes these interconnected services:

Exposed ports

Service	Port	Description
infrahub-server	8000	Web UI, GraphQL API, REST API
database	2004	Neo4j Bolt protocol (optional)
database	6362	Neo4j HTTP (optional)
message-queue	15692	RabbitMQ metrics (optional)

Data persistence

Docker Compose creates named volumes for data persistence:

database_data: Neo4j graph database
database_logs: Neo4j logs
storage_data: Artifact and file storage
workflow_db: Prefect database
workflow_data: Workflow state and logs

To back up your data:

docker compose down
docker run --rm -v infrahub_database_data:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/infrahub-backup.tar.gz /data

Updating Infrahub

Update the VERSION in .env

.env

VERSION=1.8.0

Pull new images and restart

docker compose pull
docker compose up -d

Troubleshooting

Services fail to start:

Check available resources: docker stats
Ensure ports 8000, 2004, 6362, 15692 are not in use
Review logs: docker compose logs

Database initialization takes too long:

The first start can take 1-2 minutes as Neo4j initializes
Check database logs: docker compose logs database

Cannot connect to Infrahub:

Verify all services are healthy: docker compose ps
Check firewall rules allow access to port 8000
Ensure Docker network is functioning: docker network ls

Kubernetes deployments are recommended for production environments requiring high availability and scalability.

Official Helm charts are coming soon. For now, you can create custom Kubernetes manifests based on the Docker Compose configuration.

Architecture overview

A production Kubernetes deployment should include:

StatefulSet for Neo4j database (3+ replicas for HA)
Deployment for Infrahub API servers (3+ replicas)
Deployment for task workers (2+ replicas)
StatefulSet for RabbitMQ (3 replicas for HA)
Deployment for Redis (with Redis Sentinel for HA)
Deployment for Prefect server
StatefulSet for PostgreSQL (or use cloud-managed database)
PersistentVolumeClaims for data storage
Services for internal communication
Ingress for external access

Resource requirements

Minimum pod resource requests for production:

# Infrahub API Server
resources:
  requests:
    memory: "2Gi"
    cpu: "1000m"
  limits:
    memory: "4Gi"
    cpu: "2000m"

# Neo4j Database
resources:
  requests:
    memory: "4Gi"
    cpu: "2000m"
  limits:
    memory: "8Gi"
    cpu: "4000m"

# Task Workers
resources:
  requests:
    memory: "1Gi"
    cpu: "500m"
  limits:
    memory: "2Gi"
    cpu: "1000m"

# RabbitMQ
resources:
  requests:
    memory: "1Gi"
    cpu: "500m"
  limits:
    memory: "2Gi"
    cpu: "1000m"

# Redis
resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "1Gi"
    cpu: "500m"

# Prefect Server
resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "1Gi"
    cpu: "500m"

Storage considerations

Use StorageClass with SSD-backed volumes for Neo4j
Configure backup policies for PersistentVolumes
Consider using cloud-managed databases for PostgreSQL
Use ReadWriteMany volumes for shared artifact storage if running multiple API replicas

Configuration via ConfigMap

Store Infrahub configuration in a ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: infrahub-config
data:
  INFRAHUB_DB_ADDRESS: "neo4j-service"
  INFRAHUB_DB_PORT: "7687"
  INFRAHUB_BROKER_ADDRESS: "rabbitmq-service"
  INFRAHUB_CACHE_ADDRESS: "redis-service"
  INFRAHUB_WORKFLOW_ADDRESS: "prefect-service"
  INFRAHUB_WORKFLOW_PORT: "4200"
  INFRAHUB_PRODUCTION: "true"
  INFRAHUB_LOG_LEVEL: "INFO"

Secrets management

Store sensitive data in Kubernetes Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: infrahub-secrets
type: Opaque
stringData:
  INFRAHUB_DB_USERNAME: "neo4j"
  INFRAHUB_DB_PASSWORD: "your-secure-password"
  INFRAHUB_INITIAL_ADMIN_PASSWORD: "admin-password"
  INFRAHUB_INITIAL_ADMIN_TOKEN: "admin-token"
  INFRAHUB_SECURITY_SECRET_KEY: "secret-key"
  INFRAHUB_BROKER_PASSWORD: "rabbitmq-password"

High availability setup

For production deployments:

Neo4j Cluster: Deploy 3+ Neo4j instances in cluster mode
API Server Replicas: Run 3+ API server pods behind a load balancer
RabbitMQ Cluster: Configure 3-node RabbitMQ cluster with mirrored queues
Redis Sentinel: Deploy Redis with Sentinel for automatic failover
Ingress Controller: Use NGINX or similar for external access with TLS

Monitoring and observability

Consider deploying:

Prometheus for metrics collection
Grafana for visualization
Loki or ELK Stack for log aggregation
Jaeger or Tempo for distributed tracing (if INFRAHUB_TRACE_ENABLE=true)

Network policies

Implement network policies to restrict pod-to-pod communication:

API servers can access: database, cache, message queue, task manager
Task workers can access: database, cache, message queue, task manager, API servers
Database should only accept connections from API servers and workers

For development purposes, you can run Infrahub locally using the Invoke task runner.

This method is for developers contributing to Infrahub. For regular usage, prefer Docker Compose.

Prerequisites

Python 3.12 or 3.13
uv package manager
Neo4j running locally or via Docker
Redis running locally or via Docker
RabbitMQ running locally or via Docker

Setup

Clone the repository

git clone https://github.com/opsmill/infrahub.git
cd infrahub

Install dependencies

uv sync --all-groups

Start backend services with Docker

cd development
docker compose up -d database cache message-queue task-manager task-manager-db

Run Infrahub server

cd ..
uv run invoke dev.start

Access the development instance

Navigate to http://localhost:8000

Post-installation steps

After installing Infrahub:

Change default credentials

Update the admin password through the UI or API.

Configure authentication

Set up OAuth2/OIDC providers if needed for SSO.

Install infrahubctl

Install the CLI tool for managing schemas and data:

uv tool install infrahub-sdk

Load a schema

Start with an example schema or create your own.

Next steps

Quickstart

Follow the quickstart guide to create your first objects.

Core Concepts

Learn about schemas, branches, and transformations.

Schema Library

Browse community-maintained schemas for common use cases.

Configuration Reference

Explore all available configuration options.

Get Started

Core Concepts

Schema & Data Modeling

Data Management

Version Control & Branching

Transformations & Artifacts

Integration & Automation

Deployment & Operations

Prerequisites

System requirements

Software dependencies

Installation methods

Quick installation

Service architecture

Exposed ports

Data persistence

Updating Infrahub

Troubleshooting

Architecture overview

Resource requirements

Storage considerations

Configuration via ConfigMap

Secrets management

High availability setup

Monitoring and observability

Network policies

Prerequisites

Setup

Post-installation steps

Next steps

Quickstart

Core Concepts

Schema Library

Configuration Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Schema & Data Modeling

Data Management

Version Control & Branching

Transformations & Artifacts

Integration & Automation

Deployment & Operations

​Prerequisites

​System requirements

​Software dependencies

​Installation methods

​Quick installation

​Service architecture

​Exposed ports

​Data persistence

​Updating Infrahub

​Troubleshooting

​Architecture overview

​Resource requirements

​Storage considerations

​Configuration via ConfigMap

​Secrets management

​High availability setup

​Monitoring and observability

​Network policies

​Prerequisites

​Setup

​Post-installation steps

​Next steps

Quickstart

Core Concepts

Schema Library

Configuration Reference

Build docs developers (and LLMs) love

Prerequisites

System requirements

Software dependencies

Installation methods

Quick installation

Service architecture

Exposed ports

Data persistence

Updating Infrahub

Troubleshooting

Architecture overview

Resource requirements

Storage considerations

Configuration via ConfigMap

Secrets management

High availability setup

Monitoring and observability

Network policies

Prerequisites

Setup

Post-installation steps

Next steps