Installazione Docker: avvia gitrust in 30 minuti con docker-compose¶

Obiettivi¶

Al termine di questo tutorial saprai:

O1. Distribuisci lo stack gitrust minimo (applicazione + PostgreSQL) con docker-compose
O2. Verificare che tutti e tre i servizi si avviino correttamente e siano integri
O3. Crea il primo account amministratore e accedi all'interfaccia web

Prerequisiti¶

Tecnico: una macchina VM o Linux (Debian 12 / Ubuntu 22.04 o successiva), Docker Engine ≥ 24 installato (risponde docker --version), plug-in Docker Compose installato (risponde docker compose version), porte 4000 e 2222 libere sulla macchina
Image Docker gitrust : à construire localement à partir du code source (l'image n'est pas encore publiée sur un registre public). Suivez la section Construire l'image gitrust ci-dessous avant le docker compose up.
Formativo: non è richiesto alcun tutorial gitrust preliminare: questo è il punto di partenza del percorso dell'amministratore
Tempo stimato: ~30 minuti

Construire l'image gitrust¶

Image non encore publiée

gitrust fournit un Dockerfile multi-stage (Rust + Tailwind/DaisyUI) dans le dépôt source, mais aucune image officielle n'est encore publiée sur un registre public (Docker Hub, ghcr.io, quay.io). L'installation Docker officielle est donc expérimentale : il faut cloner le dépôt et construire l'image localement. Le support Docker production sera stabilisé dans une prochaine release.

git clone https://demo.gitrust.eu/gitrust/gitrust.git
cd gitrust
docker build -t gitrust:latest .

À la fin, docker image ls | grep gitrust doit afficher l'image locale gitrust:latest. Le build prend ~8-15 min (compilation Rust en release + build CSS Tailwind). Si vous rencontrez une erreur, ouvrez une issue sur le dépôt source — le pipeline Docker n'a pas encore été testé en production.

Panoramica¶

Prima di lanciare qualsiasi comando, capiamo cosa orchestrare docker-compose e perché.

gitrust è composto da tre servizi principali nella sua configurazione minima. Immaginatelo come se tre stanze di un appartamento si chiamassero tra loro tramite una rete interna:

graph TB
    subgraph internet ["Internet / votre navigateur"]
        B[Navigateur :4000]
        S[Client git/SSH :2222]
    end

    subgraph docker ["Réseau Docker gitrust_net"]
        A["gitrust-app
(Rust, port 4000 + 2222)
Lit la config depuis .env"]
        P["postgres
(PostgreSQL 16, port 5432)
Stocke comptes, dépôts, issues"]
        R["redis (optionnel)
(Redis 7, port 6379)
Sessions web + cache"]
    end

    B -->|HTTP| A
    S -->|SSH| A
    A -->|SQL| P
    A -.->|sessions| R

gitrust-app è il nucleo: server HTTP (:4000) + server SSH (:2222) compilato in Rust. Legge la sua configurazione da un file .env e scrive semplici repository Git su un volume Docker. PostgreSQL memorizza tutti i dati relazionali (account, organizzazioni, repository, problemi, PR). Redis è facoltativo nella configurazione minima: gestisce le sessioni Web e la cache quando presente.

Dans ce tutoriel, nous utilisons la stack minimale (app + PostgreSQL) suffisante pour évaluer gitrust et démarrer une petite instance. La stack production avec Redis et SMTP se trouve dans template/docker/docker-compose.production.yml.

Passaggio 1: creare la directory di lavoro e il file di configurazione¶

Crea una directory dedicata alla tua istanza gitrust e posizionati al suo interno:

mkdir -p /opt/gitrust && cd /opt/gitrust

Crea il file di configurazione .env con i valori minimi. Devi modificare i valori contrassegnati con CHANGE_ME:

cat > .env << 'EOF'
# === gitrust — configuration minimale ===
# Changez toutes les valeurs CHANGE_ME avant de démarrer

# Clé secrète de l'application (générez avec : openssl rand -hex 32)
SECRET_KEY=CHANGE_ME_openssl_rand_hex_32

# URL publique de l'instance (sans slash final)
APP_URL=http://localhost:4000

# Base de données PostgreSQL
DATABASE_URL=postgres://gitrust:CHANGE_ME_db_password@postgres:5432/gitrust
POSTGRES_USER=gitrust
POSTGRES_PASSWORD=CHANGE_ME_db_password
POSTGRES_DB=gitrust

# Serveur SSH (port exposé à l'extérieur)
SSH_PORT=2222

# Mode de l'application
RUST_LOG=info
APP_ENV=production
EOF

Ora genera una chiave segreta robusta e sostituisci il valore in .env:

SECRET=$(openssl rand -hex 32)
sed -i "s/CHANGE_ME_openssl_rand_hex_32/$SECRET/" .env

Scegli anche una password per PostgreSQL e sostituisci entrambe le occorrenze:

DB_PASS=$(openssl rand -hex 16)
sed -i "s/CHANGE_ME_db_password/$DB_PASS/g" .env

Risultati attesi (verifica):

grep SECRET_KEY .env
# → SECRET_KEY=4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Checkpoint: esegui grep CHANGE_ME .env — il comando non dovrebbe restituire nulla. Se restituisce righe, questi valori non sono stati sostituiti e l'avvio fallirà.

Passaggio 2: crea il file docker-compose.yml¶

Crea il seguente file docker-compose.yml in /opt/gitrust/. Questo contenuto corrisponde allo stack minimo gitrust: è riprodotto qui per intero in modo che tu possa iniziare senza dipendenze esterne:

cat > docker-compose.yml << 'EOF'
# docker-compose.minimal.yml — Stack gitrust minimale (app + PostgreSQL)
# Cas d'usage : évaluation, développement, petite instance (<10 utilisateurs)
# Pour la production : utilisez docker-compose.production.yml (+ Redis + SMTP)
#
# Usage :
#   docker compose up -d
#   docker compose logs -f gitrust
#   docker compose down

version: "3.9"

services:
  # ── Base de données ───────────────────────────────────────────────────────
  postgres:
    image: postgres:16-alpine
    container_name: gitrust_postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      # Données persistantes — ne supprimez pas ce volume sans sauvegarde
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - gitrust_net

  # ── Application gitrust ───────────────────────────────────────────────────
  gitrust:
    image: gitrust:latest
    container_name: gitrust_app
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    env_file:
      # Lit toutes les variables depuis .env — ne commitez jamais ce fichier
      - .env
    ports:
      # Interface web — exposée sur toutes les interfaces de la machine hôte
      - "4000:4000"
      # Serveur SSH Git — exposé sur le port configuré dans .env
      - "${SSH_PORT:-2222}:2222"
    volumes:
      # Dépôts Git bare — données critiques, sauvegardez ce volume
      - git_repos:/var/lib/gitrust/repositories
      # Clés SSH du serveur — générées au premier démarrage, persistez-les
      - ssh_host_keys:/etc/gitrust/ssh
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    networks:
      - gitrust_net

volumes:
  # postgres_data : données relationnelles (comptes, dépôts, issues, PRs)
  postgres_data:
  # git_repos : dépôts Git bare (le contenu réel des commits)
  git_repos:
  # ssh_host_keys : clés SSH hôte (fingerprint de votre serveur)
  ssh_host_keys:

networks:
  gitrust_net:
    driver: bridge
EOF

Checkpoint: controlla che entrambi i file siano presenti in /opt/gitrust/:

ls -la /opt/gitrust/

Risultato previsto:

total 16
drwxr-xr-x 2 root root 4096 avr 17 10:00 .
drwxr-xr-x 8 root root 4096 avr 17 09:55 ..
-rw------- 1 root root  612 avr 17 10:00 .env
-rw-r--r-- 1 root root 2048 avr 17 10:00 docker-compose.yml

Passaggio 3: avvia lo stack e segui i log¶

Avvia tutti i servizi in background:

docker compose up -d

Risultato previsto:

[+] Running 4/4
 ✔ Network gitrust_gitrust_net    Created                          0.1s
 ✔ Volume "gitrust_postgres_data" Created                          0.0s
 ✔ Container gitrust_postgres     Started                          0.8s
 ✔ Container gitrust_app          Started                          1.2s

Segui i log dell'applicazione per osservare l'avvio (le migrazioni vengono eseguite automaticamente):

docker compose logs -f gitrust

Risultato previsto (primi 15-20 secondi):

gitrust_app  | 2026-04-17T10:00:15Z INFO  gitrust > Starting gitrust v0.9.0
gitrust_app  | 2026-04-17T10:00:15Z INFO  gitrust > Connecting to database...
gitrust_app  | 2026-04-17T10:00:16Z INFO  gitrust > Running database migrations...
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > Applied 42 migrations successfully
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > Generating SSH host keys...
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > SSH host key fingerprint: SHA256:xxxxxxxxxxxxxxxxxxxx
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > HTTP server listening on 0.0.0.0:4000
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > SSH server listening on 0.0.0.0:2222
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > gitrust is ready

Premere Ctrl+C per uscire dal monitoraggio del log (i contenitori continuano a essere eseguiti).

Checkpoint: verifica lo stato di salute dei servizi:

docker compose ps

Risultato previsto:

NAME              IMAGE                          COMMAND                  SERVICE    CREATED         STATUS                   PORTS
gitrust_app       gitrust:latest "/usr/local/bin/gitr…"  gitrust    2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:4000->4000/tcp, 0.0.0.0:2222->2222/tcp
gitrust_postgres  postgres:16-alpine             "docker-entrypoint.s…"  postgres   2 minutes ago   Up 2 minutes (healthy)   5432/tcp

Entrambi i contenitori dovrebbero visualizzare "(sano)". Se viene visualizzato "(avvio)", attendere 30 secondi e riprovare il comando. Se mostra "(unhealthy)", controlla i log con "docker compose logs gitrust" o "docker compose logs postgres".

Passaggio 4: crea il primo account amministratore¶

Apri il browser e vai su http://localhost:4000.

Dovresti vedere la home page di gitrust con un modulo di registrazione. Poiché l'istanza è vuota, il primo account creato diventa automaticamente amministratore.

Remplissez le formulaire : - Pseudo: il tuo identificatore amministratore (ad esempio admin) - E-mail: il tuo indirizzo email - Password: scegli una password complessa (≥ 12 caratteri)

Clicca su Crea il mio account.

Output previsto nei log (visibile con docker compose logs -f gitrust):

gitrust_app  | 2026-04-17T10:05:00Z INFO  gitrust::auth > New user registered: admin (id=1)
gitrust_app  | 2026-04-17T10:05:00Z INFO  gitrust::admin > First user promoted to administrator: admin

Checkpoint finale: accedi con le tue credenziali. Dopo aver effettuato l'accesso, verifica che il menu in alto a destra mostri un collegamento Amministrazione (o vai a http://localhost:4000/admin). Questa pagina è accessibile solo agli amministratori: la sua presenza conferma che il tuo account ha il ruolo di amministratore.

L'URL della tua istanza è "http://localhost:4000" e il tuo account amministratore è operativo.

Riepilogo¶

✓ O1 completato: lo stack docker-compose è distribuito — docker compose ps visualizza due contenitori "(sani)"
✓ O2 completato: i tre servizi (app, PostgreSQL, rete interna) si avviano correttamente — i log mostrano "gitrust è pronto" e le migrazioni vengono applicate
✓ O3 completato: il primo account amministratore viene creato e la pagina /admin è accessibile

E se non funziona¶

Symptôme	Cause probable	Correction
`Error: port 4000 is already in use` au démarrage	Un autre service occupe le port 4000 sur la machine hôte	Identifiez le service avec `ss -tlnp \\| grep 4000` ou `lsof -i :4000`. Arrêtez-le ou changez le port dans `docker-compose.yml` : remplacez `"4000:4000"` par `"4001:4000"` et accédez sur `:4001`
Le container `gitrust_app` affiche `(unhealthy)` ou redémarre en boucle	La variable `DATABASE_URL` est incorrecte ou `SECRET_KEY` contient des caractères spéciaux non échappés	Vérifiez avec `docker compose logs gitrust \\| grep ERROR`. Assurez-vous que `SECRET_KEY` est bien une chaîne hexadécimale sans guillemets. Rechargez avec `docker compose down && docker compose up -d`
La page `http://localhost:4000` affiche « Connection refused »	Le container n'est pas encore en `(healthy)` ou le port n'est pas exposé	Attendez 30 secondes et rechargez. Si le problème persiste, vérifiez que votre pare-feu local (`ufw status`) autorise le port 4000
`FATAL: password authentication failed for user "gitrust"` dans les logs postgres	Le mot de passe dans `DATABASE_URL` ne correspond pas à `POSTGRES_PASSWORD`	Supprimez le volume PostgreSQL (`docker compose down -v`) et relancez — attention : supprime toutes les données

Prossimo passo¶

→ 02 — Installazione Systemd: binario nativo + servizio: scopri l'installazione senza Docker per una distribuzione di produzione con AppArmor hardening (~45 min)

Oppure se vuoi rendere questa istanza accessibile da Internet:

→ 04 — Messa in produzione: reverse proxy TLS, SMTP, backup automatico (~90 min)

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search