Premiers pas avec gitrust : compilez, configurez et poussez votre premier commit

Source : ce tutoriel intègre le contenu de gitrust/docs/GETTING_STARTED.md avec la structure pédagogique complète (objectifs Bloom, modèle mental, checkpoints observables, section « Et si ça ne marche pas »).

Objectifs

À la fin de ce tutoriel, vous saurez :

  • O1. Compiler gitrust depuis les sources et lancer l'instance de développement localement
  • O2. Configurer l'environnement de développement (base de données, variables d'environnement, assets CSS)
  • O3. Exécuter un premier push SSH vers votre instance locale et vérifier le résultat dans l'interface web

Pré-requis

  • Technique : Rust stable ≥ 1.80 (rustc --version), PostgreSQL ≥ 15 (psql --version), Node.js ≥ 18 (node --version), Git 2.x (git --version), Docker (optionnel, recommandé pour la base de données)
  • Pédagogique : être un utilisateur autonome de gitrust (parcours user complété ou équivalent) ; familiarité avec Rust (au moins 3 mois de pratique) et avec HTTP/PostgreSQL
  • Temps estimé : ~45 minutes

Vue d'ensemble

Avant d'exécuter la première commande, prenons 3 minutes pour comprendre ce que vous allez monter et comment les pièces s'articulent.

gitrust est un monorepo Rust à 6 crates qui compile en un seul binaire. Quand vous lancez cargo run, ce binaire démarre deux serveurs simultanément : un serveur HTTP (:4000) pour l'interface web et l'API REST, et un serveur SSH (:2222) pour les opérations git push/pull. Ils partagent la même base de données PostgreSQL et le même stockage de dépôts bare sur disque.

graph TB
    subgraph sources ["Sources gitrust (monorepo Rust)"]
        C1[rustwarden-core
auth, sessions, middleware]
        C2[gitrust-core
modèles, services métier]
        C3[gitrust-git
opérations Git bare]
        C4[gitrust-web
handlers HTTP + templates]
        C5[gitrust-ssh
serveur SSH Git]
        C6[gitrust-hooks
post-receive, pre-receive]
    end

    subgraph runtime ["Processus unique (cargo run)"]
        HTTP["HTTP :4000
UI + API REST"]
        SSH["SSH :2222
git push/pull"]
    end

    subgraph storage ["Stockage"]
        PG[(PostgreSQL
comptes, dépôts,
issues, PRs)]
        REPOS[Dépôts bare
data/repos/]
    end

    C1 & C2 & C3 & C4 & C5 & C6 -->|cargo build| HTTP
    C1 & C2 & C3 & C4 & C5 & C6 -->|cargo build| SSH
    HTTP & SSH --> PG
    HTTP & SSH --> REPOS

Ce que vous allez faire : cloner les sources → préparer PostgreSQL → copier et remplir .env → compiler les assets CSS → lancer cargo run → vérifier l'instance → pousser un premier commit via SSH.

Étape 1 : Vérifiez les pré-requis système

Avant de cloner quoi que ce soit, vérifiez que tous les outils nécessaires sont installés :

rustc --version && cargo --version && psql --version && node --version && git --version

Sortie attendue (versions exactes peuvent varier) : 

rustc 1.82.0 (f6e511eec 2024-10-15)
cargo 1.82.0 (8f40fc59f 2024-10-15)
psql (PostgreSQL) 16.3
v20.11.0
git version 2.43.0

Si des dépendances système manquent, installez-les :

# Debian / Ubuntu
sudo apt install build-essential pkg-config libssl-dev libpq-dev cmake git

# macOS
brew install postgresql openssl cmake

Checkpoint : toutes les commandes de vérification doivent retourner un numéro de version sans erreur. Si rustc n'est pas trouvé, installez Rust via curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh puis rechargez votre shell.

Étape 2 : Clonez le projet

git clone https://demo.gitrust.eu/gitrust/gitrust.git
cd gitrust

Sortie attendue : 

Cloning into 'gitrust'...
remote: Enumerating objects: 12847, done.
remote: Counting objects: 100% (12847/12847), done.
Receiving objects: 100% (12847/12847), 18.42 MiB | 4.20 MiB/s, done.

Checkpoint : vérifiez que la structure de crates est présente :

ls crates/

Sortie attendue : 

gitrust-core  gitrust-git  gitrust-hooks  gitrust-ssh  gitrust-web  rustwarden-core

Étape 3 : Configurez l'environnement (.env)

Copiez le fichier d'exemple et éditez les 5 valeurs essentielles :

cp .env.example .env

Ouvrez .env dans votre éditeur et renseignez ces valeurs :

# Connexion à la base de données
DATABASE_URL=postgres://gitrust:motdepasse@localhost:5432/gitrust

# Clé secrète JWT (générez-la avec : openssl rand -hex 32)
JWT_SECRET=votre_cle_secrete_64_caracteres

# Compte administrateur créé au premier lancement
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=MotDePasseFort123!

Les autres variables ont des valeurs par défaut raisonnables pour le développement. Consultez .env.example pour la liste complète.

Générez une vraie valeur pour JWT_SECRET :

openssl rand -hex 32

Sortie attendue (valeur différente à chaque exécution) : 

4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Copiez cette valeur dans .env pour JWT_SECRET.

Checkpoint : vérifiez qu'aucune valeur d'exemple reste dans .env :

grep -E "votre_cle|example\.com|MotDePasse" .env

La commande doit retourner vide (aucune ligne). Si elle retourne des lignes, ces valeurs placeholder sont encore présentes — l'application démarrera mais avec une configuration non sécurisée.

Étape 4 : Préparez la base de données PostgreSQL

Vous avez deux options :

Option A — Docker (recommandé pour débuter) :

cd database && docker compose up -d && cd ..

Sortie attendue : 

[+] Running 2/2
 ✔ Container gitrust_postgres_dev  Started    0.8s
 ✔ Container gitrust_pgadmin       Started    1.1s

Option B — PostgreSQL existant sur la machine :

psql -U postgres << 'SQL'
CREATE USER gitrust WITH PASSWORD 'motdepasse';
CREATE DATABASE gitrust OWNER gitrust;
SQL

Sortie attendue : 

CREATE ROLE
CREATE DATABASE

Adaptez le mot de passe dans DATABASE_URL dans .env si vous utilisez l'option B.

Checkpoint : vérifiez que la base est accessible depuis l'application :

psql "$DATABASE_URL" -c "SELECT version();"

Sortie attendue : 

                                                version
-------------------------------------------------------------------------------------------------------
 PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 13.2.0-23ubuntu4) 13.2.0, 64-bit
(1 row)

Si vous obtenez psql: error: connection to server failed, vérifiez que PostgreSQL tourne et que DATABASE_URL correspond.

Étape 5 : Compilez les assets CSS

gitrust utilise Tailwind CSS + DaisyUI. Les assets doivent être compilés localement — aucun CDN, tous les fichiers sont servis depuis static/ :

npm install
npx tailwindcss -i static/css/input.css -o static/css/style.css --minify

Sortie attendue : 

added 98 packages in 3s

Rebuilding...
Done in 1842ms.

Checkpoint : vérifiez que le fichier CSS est généré :

ls -lh static/css/style.css

Sortie attendue : 

-rw-r--r-- 1 vous vous 45K avr 17 10:15 static/css/style.css

Si le fichier fait 0 octet ou n'existe pas, la compilation a échoué — relancez npm install puis la commande npx tailwindcss.

Étape 6 : Lancez l'application

cargo run

La première compilation prend 2 à 5 minutes (toutes les dépendances sont compilées). Les compilations suivantes sont incrémentales et beaucoup plus rapides.

Au premier lancement, gitrust exécute automatiquement : 1. Les migrations de base de données (création de toutes les tables) 2. La création du compte administrateur (depuis .env) 3. La génération de la clé SSH host (data/ssh_host_ed25519_key) 4. La création du répertoire de stockage des dépôts (data/repos/)

Sortie attendue (après compilation) : 

   Compiling gitrust-web v0.9.0 (/home/vous/gitrust/crates/gitrust-web)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 187.42s
     Running `target/debug/gitrust`
2026-04-17T10:20:00Z INFO  gitrust > Starting gitrust v0.9.0
2026-04-17T10:20:00Z INFO  gitrust > Running database migrations... applied 42
2026-04-17T10:20:01Z INFO  gitrust > Admin account created: admin
2026-04-17T10:20:01Z INFO  gitrust > SSH host key: SHA256:xxxxxxxxxxxxxxxxxxxx
Server listening on http://0.0.0.0:4000

Checkpoint : ouvrez http://localhost:4000 dans votre navigateur. Vous devez voir la page d'accueil gitrust. Connectez-vous avec les identifiants ADMIN_USERNAME / ADMIN_PASSWORD définis dans .env. Si la page ne charge pas, vérifiez que le message Server listening on http://0.0.0.0:4000 est bien apparu dans les logs.

Étape 7 : Créez un dépôt et poussez votre premier commit

Dans l'interface web (http://localhost:4000), cliquez sur « New repository », donnez un nom (ex. mon-projet) et cliquez Créer.

Ajoutez votre clé SSH publique dans Settings > SSH Keys en collant le contenu de ~/.ssh/id_ed25519.pub.

Puis dans votre terminal :

git clone ssh://git@localhost:2222/admin/mon-projet.git
cd mon-projet

echo "# Mon projet" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Sortie attendue : 

Cloning into 'mon-projet'...
warning: You appear to have cloned an empty repository.
[main (root-commit) a1b2c3d] Initial commit
 1 file changed, 1 insertion(+)
 create mode 100644 README.md
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 226 bytes | 226.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To ssh://localhost:2222/admin/mon-projet.git
 * [new branch]      main -> main

Checkpoint : retournez dans le navigateur sur http://localhost:4000/admin/mon-projet. La page doit afficher le fichier README.md avec le contenu # Mon projet et indiquer 1 commit sur la branche main.

Fonctionnalités supplémentaires disponibles

CI intégrée (optionnelle)

La CI s'exécute sur un serveur de build via SSH + rsync. Configurez dans .env :

# Même machine (défaut pour le développement)
CI_REMOTE_HOST=localhost

# Ou serveur dédié
CI_REMOTE_HOST=192.168.13.110
CI_REMOTE_USER=ci-runner

Easy Mode — ajoutez .gitrust-ci.yml à la racine de votre dépôt :

language: rust

build:
  command: "cargo build --release"

tests:
  command: "cargo test"

Power Mode — placez un module Dagger dans .dagger/ à la racine. gitrust exécutera dagger call -m .dagger/ ci.

Notifications

Configurez SMTP dans .env pour les notifications e-mail :

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user
SMTP_PASSWORD=password
SMTP_FROM=noreply@gitrust.eu

Langue de l'interface

gitrust est disponible en 6 langues (fr, en, de, es, pt, it). Définissez la langue par défaut de l'instance :

DEFAULT_LOCALE=fr

Récapitulatif

  • ✓ O1 accompli : gitrust est compilé depuis les sources et tourne localement — cargo run affiche « Server listening on http://0.0.0.0:4000 »
  • ✓ O2 accompli : l'environnement est configuré — .env rempli, PostgreSQL connecté, assets CSS générés, migrations appliquées
  • ✓ O3 accompli : un premier push SSH a réussi — le commit est visible dans l'interface web à http://localhost:4000/admin/mon-projet

Et si ça ne marche pas

Symptôme Cause probable Correction
error[E0463]: can't find crate for 'std' à la compilation Toolchain Rust manquante ou mauvaise version Exécutez rustup update stable && rustup default stable. Vérifiez avec rustc --version ≥ 1.80
connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed PostgreSQL non démarré ou DATABASE_URL incorrect Démarrez PostgreSQL (sudo systemctl start postgresql ou docker compose up -d dans database/). Vérifiez que DATABASE_URL dans .env correspond
Permission denied (publickey) lors du git push Clé SSH non enregistrée dans gitrust ou mauvais port Vérifiez dans Settings > SSH Keys que la clé est présente. Testez avec ssh -T git@localhost -p 2222 — vous devez voir « Vous êtes authentifié »

Prochaine étape

→ 02 — Première contribution : clone, build, test, PR : apprenez à créer une feature branch, écrire des tests, et soumettre votre première pull request en suivant le workflow gitrust (~90 min)