Skip to main content

​
Self-Hosting Overview

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

​
Why Self-Host?

Data Sovereignty

Your source code and analysis data never leave your infrastructure. All processing happens within your network.

Compliance

Meet regulatory requirements that mandate data residency, audit controls, or air-gapped environments.

Custom AI Models

Use your own AI model provider — any OpenAI-compatible API works. Run models locally or through your preferred vendor.

Network Isolation

Deploy behind your firewall with no inbound internet access required beyond GitHub webhooks and AI provider APIs.

​
Deployment Options

ScenarioRecommendation
Small team (under 50 developers)Docker Compose
Large team (50+ developers)Kubernetes
High availability requiredKubernetes

​
Architecture

Octokraft consists of three application components backed by four infrastructure services: 
+-----------------------------------------------------------------+
|                          Octokraft                              |
+-----------------------------------------------------------------+
|  +---------------+  +---------------+  +-----------------------+ |
|  |    Web App    |  |  API Server   |  |   Analysis Workers    | |
|  |   (Frontend)  |  |               |  |                       | |
|  +---------------+  +---------------+  +-----------------------+ |
+-----------------------------------------------------------------+
|  +----------+ +---------+ +------------+ +--------------------+ |
|  | Postgres | |  Redis  | |  FalkorDB  | |      Temporal      | |
|  +----------+ +---------+ +------------+ +--------------------+ |
+-----------------------------------------------------------------+
ComponentRole
Web AppThe Octokraft frontend. Serves the dashboard, PR views, and project settings.
API ServerHandles HTTP requests, authenticates users, and coordinates with infrastructure services.
Analysis WorkersProcess 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 Octokraft or be managed separately (e.g., cloud-managed Postgres, hosted Redis).
ServicePurposeMinimum Version
PostgreSQLPrimary data store for projects, users, analysis results, health assessments, and all persistent data16+
RedisCaching, real-time event delivery (pub/sub for SSE), and session data7+
FalkorDBGraph database for the code knowledge graph — symbols, dependencies, and cross-file relationshipsLatest
TemporalWorkflow orchestration for analysis pipelines, onboarding, and background processingLatest
All four services are required. Octokraft will not start if any service is unreachable.

​
AI Model Configuration

Octokraft 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 for details on the 4 model slots (large/small variants for OpenAI and Anthropic providers).

​
System Requirements

​
Docker Compose (small teams)

ResourceMinimumRecommended
CPU4 cores8 cores
Memory8 GB16 GB
Disk50 GB SSD100 GB SSD

​
Kubernetes (large teams)

ComponentCPU RequestMemory RequestReplicas
API Server500m512 Mi2+
Analysis Workers1000m1 Gi2+
Web App100m128 Mi2+
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

PortPurpose
443 (HTTPS)User access to the web application and API

​
Outbound

DestinationPurpose
GitHub API (api.github.com)Repository access, webhook management, PR operations
AI Provider APIModel inference for code analysis (varies by provider)
If you use a self-hosted AI model provider, no outbound access to external AI APIs is needed.

​
Next Steps

Docker Compose

Step-by-step deployment guide for small teams.

Kubernetes

Production deployment on Kubernetes with scaling and high availability.

Configuration Reference

Complete list of environment variables and their descriptions.