Skip to content
Proval

Quick Start

Run Proval with Docker Compose and open the dashboard.

Requirements

  • Docker and Docker Compose on the machine that will host Proval

Run with Docker Compose

Create a docker-compose.yml file:

services:
    proval:
        image: ghcr.io/seoes/proval:latest
        ports:
            - "7900:7900"
            - "7901:7901"
        volumes:
            - ./data:/data
        environment:
            - ENCRYPTION_KEY=[Encryption Key]

ENCRYPTION_KEY is a random string generated by openssl rand -base64 32.

openssl rand -base64 32

LAN HTTP needs no extra setting. When the dashboard is served over HTTPS, set COOKIE_SECURE=true (see HTTPS).

Start the stack:

docker compose up -d

On your browser, open the dashboard:

Proval dashboard in the browser 
http://<your-server>:7900

Replace <your-server> with your server hostname or IP address.

Network

Port Purpose
7900 Dashboard
7901 Receive Webhooks

Configure your Git provider to send webhooks to port 7901 on your Proval instance.

http://<your-server>:7901/webhook/gitlab
http://<your-server>:7901/webhook/forgejo
http://<your-server>:7901/webhook/github

On a private LAN, GitLab and Forgejo block http:// webhook URLs by default. Before you use one, follow the setup in the GitLab and Forgejo guides.

HTTPS

GitHub requires a public https:// URL for webhooks. Set up HTTPS before you connect.

To use HTTPS, put a reverse proxy in front of Proval. When the dashboard is reached over HTTPS, set COOKIE_SECURE=true on the Proval container so the browser will not send proval_session on plain HTTP.

Common choices:

  • nginx
  • Caddy
  • Traefik
  • Cloudflare Tunnel
http://<your-server>:7901/webhook/gitlab  →  https://example.com/webhook/gitlab

Details depend on your Git host. See GitLab, Forgejo, or GitHub.

What's next

  1. Optional: run on Kubernetes with the Kubernetes example
  2. Set LLM, or OpenRouter / llama.cpp for example endpoint values
  3. Your Git provider: GitLab · Forgejo · GitHub