title: "Installation Guide"

OpenCodeHub is a self-hosted Git platform. You can run it via Docker (recommended) or Node.js (for development).

System Requirements

CLI Installation (opencodehub-cli)

Install the official OpenCodeHub CLI (och) to manage stacks, pull requests, and merge queues from your terminal:

# via npm
npm install -g opencodehub-cli

# via bun
bun add -g opencodehub-cli

# via pnpm
pnpm add -g opencodehub-cli

# via yarn
yarn global add opencodehub-cli

Verify your installation:

och --version
och --help

1-Click Installation (Recommended)

curl -sSL https://raw.githubusercontent.com/swadhinbiswas/OpencodeHub/main/install.sh | bash

The script will:

1. Ensure Docker and Docker Compose are installed
2. Clone the latest stable release
3. Configure a unified DATA_DIR for databases, git repos, and storage
4. Prompt you to create an initial admin user

Manual Docker Setup

# Clone
git clone https://github.com/swadhinbiswas/OpencodeHub.git
cd OpencodeHub

# Configure
cp .env.example .env
# Edit .env — at minimum, change all secrets!

# Start
docker-compose up -d

# Create admin user
docker-compose exec app bun run scripts/seed-admin.ts

The app runs on port 4321 (HTTP) and port 2222 (SSH git).

:::caution[Change Secrets]
Before going live, generate new secrets for all *_SECRET and *_KEY variables:

openssl rand -base64 32

:::

Docker Compose Services

Nginx Reverse Proxy (SSL)

In production, use HTTPS. Standard Nginx config:

server {
    listen 80;
    server_name git.yourcompany.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name git.yourcompany.com;

    ssl_certificate /etc/letsencrypt/live/git.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.yourcompany.com/privkey.pem;

    # Important for Git operations
    client_max_body_size 500M;

    location / {
        proxy_pass http://localhost:4321;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

See Nginx Deployment for the full config with WebSocket support and Git optimizations.

SSH Git Access

The SSH git server starts automatically on port 2222. Clone with:

git clone ssh://git@your-server:2222/owner/repo.git

The host key is auto-generated at GIT_SSH_HOST_KEY on first start.

Node.js Setup (Development)

# Install dependencies
npm install

# Configure
cp .env.example .env

# Push schema to database
npm run db:push

# Create admin user
bun run scripts/seed-admin.ts

# Start dev server
npm run dev

See Local Dev Setup for details.

Production Checklist

Before going live:

• All secrets rotated (JWT_SECRET, SESSION_SECRET, INTERNAL_HOOK_SECRET, etc.)
• HTTPS enabled via Nginx/Caddy
• PostgreSQL used (not SQLite)
• Redis configured for distributed locking
• Rate limiting enabled (RATE_LIMIT_ENABLED=true)
• Email configured (SMTP) for notifications
• Storage backend configured (S3 recommended for multi-node)
• Backup strategy configured
• Monitoring set up (see Monitoring)

Next Steps

• Quick Start Guide — Navigate the dashboard and create your first repo
• Configuration Reference — All environment variables
• Docker Deployment — Production Docker setup