Installation

Install Infrahub using Docker Compose or Kubernetes for development, testing, or production environments.

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

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

Kubernetes

• Kubernetes cluster 1.24+
• kubectl configured for your cluster
• Helm 3.8+ (recommended)
• Persistent volume provisioner

Installation methods

Docker Compose

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

Quick installation

1. Create a directory for Infrahub

   mkdir infrahub
   cd infrahub
   
2. Download the Docker Compose file

   curl -O https://raw.githubusercontent.com/opsmill/infrahub/stable/docker-compose.yml
   
3. 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.

4. 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)
5. Verify the installation

   Check service health:

   docker compose ps
   

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

   docker compose logs -f infrahub-server
   
6. Access Infrahub

   Open your browser to:

   http://localhost:8000
   

   Login with:

   • 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

1. Update the VERSION in .env

   .env

   VERSION=1.8.0
   
2. 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

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:

1. Neo4j Cluster: Deploy 3+ Neo4j instances in cluster mode
2. API Server Replicas: Run 3+ API server pods behind a load balancer
3. RabbitMQ Cluster: Configure 3-node RabbitMQ cluster with mirrored queues
4. Redis Sentinel: Deploy Redis with Sentinel for automatic failover
5. 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

Development (Invoke)

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

1. Clone the repository

   git clone https://github.com/opsmill/infrahub.git
   cd infrahub
   
2. Install dependencies

   uv sync --all-groups
   
3. Start backend services with Docker

   cd development
   docker compose up -d database cache message-queue task-manager task-manager-db
   
4. Run Infrahub server

   cd ..
   uv run invoke dev.start
   
5. Access the development instance

   Navigate to http://localhost:8000

Post-installation steps

After installing Infrahub:

1. Change default credentials

   Update the admin password through the UI or API.

2. Configure authentication

   Set up OAuth2/OIDC providers if needed for SSO.

3. Install infrahubctl

   Install the CLI tool for managing schemas and data:

   uv tool install infrahub-sdk
   
4. 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.