Installation Docker : démarrez gitrust en 30 minutes avec docker-compose¶

Objectifs¶

À la fin de ce tutoriel, vous saurez :

• O1. Déployer la stack gitrust minimale (application + PostgreSQL) avec docker-compose
• O2. Vérifier que les trois services démarrent correctement et sont en bonne santé
• O3. Créer le premier compte administrateur et accéder à l'interface web

Pré-requis¶

• Technique : une VM ou machine Linux (Debian 12 / Ubuntu 22.04 ou supérieur), Docker Engine ≥ 24 installé (docker --version répond), Docker Compose plugin installé (docker compose version répond), ports 4000 et 2222 libres sur la machine
• Pédagogique : aucun tutoriel gitrust préalable requis — c'est le point de départ du parcours administrateur
• Temps estimé : ~30 minutes

Vue d'ensemble¶

Avant de lancer la moindre commande, comprenons ce que docker-compose va orchestrer et pourquoi.

gitrust est composé de trois services principaux dans sa configuration minimale. Pensez-y comme trois pièces d'un appartement qui s'appellent entre elles via un réseau interne :

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 est le cœur : serveur HTTP (:4000) + serveur SSH (:2222) compilé en Rust. Il lit sa configuration depuis un fichier .env et écrit les dépôts Git bare sur un volume Docker. PostgreSQL stocke toutes les données relationnelles (comptes, organisations, dépôts, issues, PRs). Redis est optionnel dans la configuration minimale — il gère les sessions web et le cache quand il est présent.

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.

Étape 1 : Créez le répertoire de travail et le fichier de configuration¶

Créez un répertoire dédié à votre instance gitrust et positionnez-vous dedans :

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

Créez le fichier de configuration .env avec les valeurs minimales. Changez impérativement les valeurs marquées 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

Générez maintenant une clé secrète robuste et remplacez la valeur dans .env :

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

Choisissez également un mot de passe pour PostgreSQL et remplacez les deux occurrences :

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

Sortie attendue (vérification) :

grep SECRET_KEY .env
# → SECRET_KEY=4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Checkpoint : exécutez grep CHANGE_ME .env — la commande doit ne rien retourner. Si elle retourne des lignes, ces valeurs n'ont pas été remplacées et le démarrage échouera.

Étape 2 : Créez le fichier docker-compose.yml¶

Créez le fichier docker-compose.yml suivant dans /opt/gitrust/. Ce contenu correspond à la stack minimale gitrust — il est reproduit ici intégralement pour que vous puissiez démarrer sans dépendance externe :

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: ghcr.io/gitrust/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 : vérifiez que les deux fichiers sont présents dans /opt/gitrust/ :

ls -la /opt/gitrust/

Sortie attendue :

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

Étape 3 : Démarrez la stack et suivez les logs¶

Démarrez tous les services en arrière-plan :

docker compose up -d

Sortie attendue :

[+] 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

Suivez les logs de l'application pour observer le démarrage (les migrations s'exécutent automatiquement) :

docker compose logs -f gitrust

Sortie attendue (les 15-20 premières secondes) :

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

Appuyez sur Ctrl+C pour quitter le suivi des logs (les containers continuent de tourner).

Checkpoint : vérifiez l'état de santé des services :

docker compose ps

Sortie attendue :

NAME              IMAGE                          COMMAND                  SERVICE    CREATED         STATUS                   PORTS
gitrust_app       ghcr.io/gitrust/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

Les deux containers doivent afficher (healthy). Si l'un affiche (starting), attendez 30 secondes et relancez la commande. S'il affiche (unhealthy), consultez les logs avec docker compose logs gitrust ou docker compose logs postgres.

Étape 4 : Créez le premier compte administrateur¶

Ouvrez votre navigateur et rendez-vous sur http://localhost:4000.

Vous devriez voir la page d'accueil gitrust avec un formulaire d'inscription. Comme l'instance est vierge, le premier compte créé devient automatiquement administrateur.

Remplissez le formulaire : - Pseudo : votre identifiant administrateur (ex. admin) - E-mail : votre adresse e-mail - Mot de passe : choisissez un mot de passe robuste (≥ 12 caractères)

Cliquez sur Créer mon compte.

Sortie attendue dans les logs (visible avec 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 final : connectez-vous avec vos identifiants. Après la connexion, vérifiez que le menu en haut à droite affiche un lien Administration (ou naviguez vers http://localhost:4000/admin). Cette page n'est accessible qu'aux administrateurs — sa présence confirme que votre compte a bien le rôle admin.

L'URL de votre instance est http://localhost:4000 et votre compte administrateur est opérationnel.

Récapitulatif¶

• ✓ O1 accompli : la stack docker-compose est déployée — docker compose ps affiche deux containers (healthy)
• ✓ O2 accompli : les trois services (app, PostgreSQL, réseau interne) démarrent correctement — les logs montrent « gitrust is ready » et les migrations sont appliquées
• ✓ O3 accompli : le premier compte administrateur est créé et la page /admin est accessible

Et si ça ne marche pas¶

Prochaine étape¶

→ 02 — Installation systemd : binaire natif + service : découvrez l'installation sans Docker pour un déploiement production avec hardening AppArmor (~45 min)

Ou si vous souhaitez rendre cette instance accessible depuis Internet :

→ 04 — Mise en production : reverse-proxy TLS, SMTP, sauvegarde automatique (~90 min)