> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octokraft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosting Overview

> Deploy Corbulo in your own infrastructure

# Self-Hosting Overview

Corbulo can be deployed in your own infrastructure for teams that need full control over their data, compliance posture, or network environment.

***

## Why Self-Host?

<CardGroup cols={2}>
  <Card title="Data Sovereignty" icon="shield-halved">
    Your source code and analysis data never leave your infrastructure. All processing happens within your network.
  </Card>

  <Card title="Compliance" icon="file-shield">
    Meet regulatory requirements that mandate data residency, audit controls, or air-gapped environments.
  </Card>

  <Card title="Custom AI Models" icon="microchip">
    Use your own AI model provider -- any OpenAI-compatible API works. Run models locally or through your preferred vendor.
  </Card>

  <Card title="Network Isolation" icon="lock">
    Deploy behind your firewall with no inbound internet access required beyond GitHub webhooks and AI provider APIs.
  </Card>
</CardGroup>

***

## Deployment Options

| Scenario                         | Recommendation                                 |
| -------------------------------- | ---------------------------------------------- |
| Small team (under 50 developers) | [Docker Compose](/self-hosting/docker-compose) |
| Large team (50+ developers)      | [Kubernetes](/self-hosting/kubernetes)         |
| High availability required       | [Kubernetes](/self-hosting/kubernetes)         |

***

## Architecture

Corbulo consists of three application components backed by four infrastructure services:

```
+-----------------------------------------------------------------+
|                          Corbulo                              |
+-----------------------------------------------------------------+
|  +---------------+  +---------------+  +-----------------------+ |
|  |    Web App    |  |  API Server   |  |   Analysis Workers    | |
|  |   (Frontend)  |  |               |  |                       | |
|  +---------------+  +---------------+  +-----------------------+ |
+-----------------------------------------------------------------+
|  +----------+ +---------+ +------------+ +--------------------+ |
|  | Postgres | |  Redis  | |  FalkorDB  | |      Temporal      | |
|  +----------+ +---------+ +------------+ +--------------------+ |
+-----------------------------------------------------------------+
```

| Component            | Role                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Web App**          | The Corbulo frontend. Serves the dashboard, PR views, and project settings.                                              |
| **API Server**       | Handles HTTP requests, authenticates users, and coordinates with infrastructure services.                                |
| **Analysis Workers** | Process background tasks: code analysis, health assessments, PR analysis, convention detection, and architecture review. |

***

## Required Infrastructure

You need to provision the following services. They can run alongside Corbulo or be managed separately (e.g., cloud-managed Postgres, hosted Redis).

| Service        | Purpose                                                                                               | Minimum Version |
| -------------- | ----------------------------------------------------------------------------------------------------- | --------------- |
| **PostgreSQL** | Primary data store for projects, users, analysis results, health assessments, and all persistent data | 16+             |
| **Redis**      | Caching, real-time event delivery (pub/sub for SSE), and session data                                 | 7+              |
| **FalkorDB**   | Graph database for the code knowledge graph -- symbols, dependencies, and cross-file relationships    | Latest          |
| **Temporal**   | Workflow orchestration for analysis pipelines, onboarding, and background processing                  | Latest          |

<Note>
  All four services are required. Corbulo will not start if any service is unreachable.
</Note>

***

## AI Model Configuration

Corbulo requires access to AI models for code analysis, architecture review, convention detection, and PR analysis. Any OpenAI-compatible API works, including:

* OpenAI
* Azure OpenAI
* Anthropic (via OpenAI-compatible endpoints)
* OpenRouter
* Self-hosted models (vLLM, Ollama, etc.)

AI model configuration is done through environment variables. See the [Configuration Reference](/self-hosting/configuration) for details on the 4 model slots (large/small variants for OpenAI and Anthropic providers).

***

## System Requirements

### Docker Compose (small teams)

| Resource   | Minimum   | Recommended |
| ---------- | --------- | ----------- |
| **CPU**    | 4 cores   | 8 cores     |
| **Memory** | 8 GB      | 16 GB       |
| **Disk**   | 50 GB SSD | 100 GB SSD  |

### Kubernetes (large teams)

| Component            | CPU Request | Memory Request | Replicas |
| -------------------- | ----------- | -------------- | -------- |
| **API Server**       | 500m        | 512 Mi         | 2+       |
| **Analysis Workers** | 1000m       | 1 Gi           | 2+       |
| **Web App**          | 100m        | 128 Mi         | 2+       |

Infrastructure services (PostgreSQL, Redis, FalkorDB, Temporal) should be sized according to your repository count and team size. For production deployments with 50+ developers, use managed database services or dedicated nodes.

***

## Networking

### Inbound

| Port            | Purpose                                    |
| --------------- | ------------------------------------------ |
| **443** (HTTPS) | User access to the web application and API |

### Outbound

| Destination                       | Purpose                                                |
| --------------------------------- | ------------------------------------------------------ |
| **GitHub API** (`api.github.com`) | Repository access, webhook management, PR operations   |
| **AI Provider API**               | Model inference for code analysis (varies by provider) |

<Note>
  If you use a self-hosted AI model provider, no outbound access to external AI APIs is needed.
</Note>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Docker Compose" icon="docker" href="/self-hosting/docker-compose">
    Step-by-step deployment guide for small teams.
  </Card>

  <Card title="Kubernetes" icon="dharmachakra" href="/self-hosting/kubernetes">
    Production deployment on Kubernetes with scaling and high availability.
  </Card>

  <Card title="Configuration Reference" icon="gear" href="/self-hosting/configuration">
    Complete list of environment variables and their descriptions.
  </Card>
</CardGroup>