Installation

GitRiver is a self-hosted git platform shipped as a single Rust binary. It only requires PostgreSQL to run. This section covers three installation methods: quick start with Docker Compose, production deployment with nginx and SSL, and building from source.

System Requirements

Parameter	GitRiver only	With CI runner	Production
CPU	1 vCPU	2+ cores	8+ cores
RAM	256 MB	4+ GB	16+ GB
Disk	10 GB	20 GB	100+ GB SSD
PostgreSQL	16+	16+	18+
Docker	-	20.10+ with BuildKit	latest stable

GitRiver uses ~100 MB of RAM at idle. Docker is only needed for CI tasks. Without CI you can run without Docker.

---

Quick Start (Docker Compose)

The simplest way to run GitRiver is Docker Compose. Two containers: PostgreSQL and GitRiver.

1. Create two files

.env — database settings (password in one place):

DB_USER=gitriver
DB_PASS=changeme
DB_NAME=gitriver

docker-compose.yml:

services:
  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASS}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 5s
      retries: 5

  gitriver:
    image: gitriver/gitriver:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "3000:3000"
    environment:
      GITRIVER_DB_HOST: postgres
      GITRIVER_DB_PORT: 5432
      GITRIVER_DB_USER: ${DB_USER}
      GITRIVER_DB_PASS: ${DB_PASS}
      GITRIVER_DB_NAME: ${DB_NAME}
    volumes:
      - ./data/gitriver:/var/lib/gitriver
      - /var/run/docker.sock:/var/run/docker.sock

Replace changeme with a strong password in the .env file.

2. Start

docker compose up -d

Docker Compose will bring up:

• postgres (PostgreSQL 17) - database on port 5432 (internal)
• gitriver - web server on port 3000

3. Open in browser

Navigate to http://localhost:3000. The setup wizard will appear.

4. Complete the setup wizard

The setup wizard appears on first launch until an administrator is created.

1. Database connection - if you set the GITRIVER_DB_* variables in docker-compose, the fields will be filled automatically. Click “Test connection” to verify.
2. Create administrator - enter a username, email, and password.
3. Instance name - the display name of your installation.

After completion, the server will restart in normal mode.

---

Production Installation

For production, it is recommended to use: separate volumes for data, strong passwords, nginx with SSL, Docker socket passthrough for CI.

1. Prepare directories

mkdir -p /opt/gitriver/data/{gitriver,postgres}
cd /opt/gitriver

2. Create .env

cat > .env << 'EOF'
GITRIVER_DB_HOST=postgres
GITRIVER_DB_PORT=5432
GITRIVER_DB_USER=gitriver
GITRIVER_DB_PASS=generate_a_strong_password
GITRIVER_DB_NAME=gitriver
GITRIVER_BASE_URL=https://git.example.com
EOF

GITRIVER_BASE_URL - the external URL of your instance. Used for links in email notifications, CI variables, and webhooks.

3. Create docker-compose.yml

services:
  postgres:
    image: postgres:18-alpine
    restart: always
    environment:
      POSTGRES_USER: ${GITRIVER_DB_USER}
      POSTGRES_PASSWORD: ${GITRIVER_DB_PASS}
      POSTGRES_DB: ${GITRIVER_DB_NAME}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: pg_isready -U ${GITRIVER_DB_USER}
      interval: 5s
      timeout: 3s
      retries: 5

  gitriver:
    image: gitriver/gitriver:latest
    restart: always
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "3000:3000"
    volumes:
      - ./data/gitriver:/var/lib/gitriver
      - /var/run/docker.sock:/var/run/docker.sock
    env_file: .env

Docker socket (/var/run/docker.sock) is needed to run CI tasks. If you don’t use CI - you can skip mounting it.

4. Start

docker compose up -d

5. Configure nginx

GitRiver listens on port 3000. For HTTPS, place nginx in front of it:

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

    ssl_certificate     /etc/ssl/certs/git.example.com.pem;
    ssl_certificate_key /etc/ssl/private/git.example.com.key;

    # For git push of large repositories and LFS
    client_max_body_size 512m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;

        # SSE - real-time CI log streaming
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

proxy_buffering off is required: without it, CI log streaming and SSE events will not work.

6. Open in browser

Navigate to https://git.example.com and complete the setup wizard.

---

SSH Access

GitRiver has a built-in SSH server for git clone / git push over SSH.

Setup

1. Log in to GitRiver and open Settings (gear icon in the top right corner)
2. Go to the SSH Keys section
3. Click “Add SSH Key”
4. Paste the contents of your public key (~/.ssh/id_ed25519.pub)

Cloning via SSH

git clone ssh://git@git.example.com/owner/repo.git

In Docker, you need to expose the SSH port and configure authorized_keys_path in the config. See the Configuration section for details.

---

Updating

Docker

cd /opt/gitriver
docker compose pull gitriver
docker compose up -d gitriver