Erste Schritte mit Gitrust: Kompilieren, konfigurieren und pushen Sie Ihren ersten 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 »).

Ziele

Am Ende dieses Tutorials wissen Sie:

  • **O1. Kompilieren Sie Gitrust aus dem Quellcode und starten Sie die Entwicklungsinstanz lokal
  • O2. Konfigurieren Sie die Entwicklungsumgebung (Datenbank, Umgebungsvariablen, CSS-Assets)
  • O3. Führen Sie einen ersten SSH-Push zu Ihrer lokalen Instanz aus und überprüfen Sie das Ergebnis im Webinterface

Voraussetzungen

  • Technisch: Rust Stable ≥ 1.80 (rustc --version), PostgreSQL ≥ 15 (psql --version), Node.js ≥ 18 (node --version), Git 2.x (git --version), Docker (optional, empfohlen für die Datenbank)
  • 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
  • Geschätzte Zeit: ~45 Minuten

Überblick

Bevor wir den ersten Befehl ausführen, nehmen wir uns 3 Minuten Zeit, um zu verstehen, was Sie zusammenbauen werden und wie die Teile zusammenpassen.

gitrust ist ein Rust-Monorepo mit 6 Kisten, das zu einer einzigen Binärdatei kompiliert wird. Wenn Sie „cargo run“ ausführen, startet diese Binärdatei zwei Server gleichzeitig: einen HTTP-Server („:4000“) für die Webschnittstelle und die REST-API sowie einen SSH-Server („:2222“) für „git push/pull“-Vorgänge. Sie teilen sich die gleiche PostgreSQL-Datenbank und den gleichen Bare-Disk-Repository-Speicher.

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

Was Sie tun werden: die Quellen klonen → PostgreSQL vorbereiten → „.env“ kopieren und füllen → die CSS-Assets kompilieren → „Cargo Run“ ausführen → die Instanz überprüfen → einen ersten Commit über SSH pushen.

Schritt 1: Systemanforderungen prüfen

Stellen Sie vor dem Klonen sicher, dass alle erforderlichen Tools installiert sind:

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

Erwartete Ausgabe (genaue Versionen können variieren): 

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

Falls Systemabhängigkeiten fehlen, installieren Sie diese:

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

# macOS
brew install postgresql openssl cmake

Checkpoint: Alle Prüfbefehle müssen eine fehlerfreie Versionsnummer zurückgeben. Wenn „rustc“ nicht gefunden wird, installieren Sie Rust über „curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs |“. sh`, dann lade deine Shell neu.

Schritt 2: Klonen Sie das Projekt

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

Erwartete Ausgabe: 

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: Überprüfen Sie, ob die Kistenstruktur vorhanden ist:

ls crates/

Erwartete Ausgabe: 

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

Schritt 3: Konfigurieren Sie die Umgebung (.env)

Kopieren Sie die Beispieldatei und bearbeiten Sie die 5 wesentlichen Werte:

cp .env.example .env

Öffnen Sie „.env“ in Ihrem Editor und geben Sie diese Werte ein:

# 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.

Generieren Sie einen echten Wert für „JWT_SECRET“:

openssl rand -hex 32

Erwartete Ausgabe (unterschiedlicher Wert bei jedem Lauf): 

4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Kopieren Sie diesen Wert nach „.env“ für „JWT_SECRET“.

Checkpoint: Überprüfen Sie, ob in „.env“ keine Beispielwerte verbleiben:

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

Der Befehl sollte leer zurückkommen (keine Zeilen). Wenn Zeilen zurückgegeben werden, sind diese Platzhalterwerte weiterhin vorhanden – die Anwendung wird gestartet, jedoch mit einer unsicheren Konfiguration.

Schritt 4: Bereiten Sie die PostgreSQL-Datenbank vor

Sie haben zwei Möglichkeiten:

Option A – Docker (empfohlen für Anfänger):

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

Erwartete Ausgabe: 

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

Option B – PostgreSQL auf dem Computer vorhanden:

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

Erwartete Ausgabe: 

CREATE ROLE
CREATE DATABASE

Passen Sie das Passwort in „DATABASE_URL“ in „.env“ an, wenn Sie Option B verwenden.

Checkpoint: Überprüfen Sie, ob die Basis über die Anwendung zugänglich ist:

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

Erwartete Ausgabe: 

                                                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)

Wenn Sie „psql: Fehler: Verbindung zum Server fehlgeschlagen“ erhalten, überprüfen Sie, ob PostgreSQL ausgeführt wird und ob „DATABASE_URL“ übereinstimmt.

Schritt 5: Kompilieren Sie die CSS-Assets

Gitrust verwendet Tailwind CSS + DaisyUI. Assets müssen lokal kompiliert werden – kein CDN, alle Dateien werden von „static/“ bereitgestellt:

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

Erwartete Ausgabe: 

added 98 packages in 3s

Rebuilding...
Done in 1842ms.

Checkpoint: Überprüfen Sie, ob die CSS-Datei generiert wurde:

ls -lh static/css/style.css

Erwartete Ausgabe: 

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

Wenn die Datei 0 Byte groß ist oder nicht existiert, ist die Kompilierung fehlgeschlagen – führen Sie „npm install“ erneut aus und dann den Befehl „npx tailwindcss“.

Schritt 6: Starten Sie die App

cargo run

Die erste Kompilierung dauert 2-5 Minuten (alle Abhängigkeiten werden kompiliert). Nachfolgende Kompilierungen erfolgen inkrementell und viel schneller.

Au premier lancement, gitrust exécute automatiquement : 1. Datenbankmigrationen (Erstellung aller Tabellen) 2. Erstellen des Administratorkontos (aus „.env“) 3. Generieren des SSH-Hostschlüssels („data/ssh_host_ed25519_key“) 4. Erstellen des Repository-Speicherverzeichnisses („data/repos/“)

Erwartete Ausgabe (nach der Kompilierung): 

   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: Öffnen Sie „http://localhost:4000“ in Ihrem Browser. Sie müssen die Gitrust-Homepage sehen. Melden Sie sich mit den in „.env“ definierten Anmeldeinformationen „ADMIN_USERNAME“ / „ADMIN_PASSWORD“ an. Wenn die Seite nicht geladen wird, überprüfen Sie, ob in den Protokollen die Meldung „Server lauscht auf http://0.0.0.0:4000“ erscheint.

Schritt 7: Erstellen Sie ein Repository und übertragen Sie Ihren ersten Commit

Klicken Sie in der Weboberfläche („http://localhost:4000“) auf „Neues Repository“, geben Sie einen Namen ein (z. B. „mein-Projekt“) und klicken Sie auf Erstellen.

Fügen Sie Ihren öffentlichen SSH-Schlüssel unter Einstellungen > SSH-Schlüssel hinzu, indem Sie den Inhalt von „~/.ssh/id_ed25519.pub“ einfügen.

Dann in Ihrem 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

Erwartete Ausgabe: 

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: Kehren Sie zum Browser zu „http://localhost:4000/admin/my-project“ zurück. Die Seite sollte die Datei „README.md“ mit dem Inhalt „#Mein Projekt“ anzeigen und 1 Commit im Zweig „Haupt“ anzeigen.

Zusätzliche Funktionen verfügbar

Integrierter IC (optional)

Das CI läuft auf einem Build-Server über SSH + rsync. Konfigurieren Sie in „.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

Einfacher Modus – fügen Sie „.gitrust-ci.yml“ zum Stammverzeichnis Ihres Repositorys hinzu:

language: rust

build:
  command: "cargo build --release"

tests:
  command: "cargo test"

Power-Modus – Platzieren Sie ein Dagger-Modul in „.dagger/“ im Stammverzeichnis. Gitrust führt „dagger call -m .dagger/ ci“ aus.

Benachrichtigungen

Konfigurieren Sie SMTP in „.env“ für E-Mail-Benachrichtigungen:

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

Schnittstellensprache

Gitrust ist in 6 Sprachen verfügbar (fr, en, de, es, pt, it). Legen Sie die Standardsprache für die Instanz fest:

DEFAULT_LOCALE=fr

Zusammenfassung

  • ✓ O1 erreicht: Gitrust wird aus dem Quellcode kompiliert und lokal ausgeführt – „Cargo Run“ zeigt „Server lauscht auf http://0.0.0.0:4000“ an.
  • ✓ O2 abgeschlossen: Die Umgebung ist konfiguriert – „.env“ ausgefüllt, PostgreSQL verbunden, CSS-Assets generiert, Migrationen angewendet
  • ✓ O3 abgeschlossen: Ein erster SSH-Push war erfolgreich – der Commit ist im Webinterface unter „http://localhost:4000/admin/mon-project“ sichtbar

Und wenn es nicht klappt

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é »

Nächster Schritt

→ 02 – Erster Beitrag: Klonen, Erstellen, Testen, PR: Erfahren Sie, wie Sie einen Feature-Branch erstellen, Tests schreiben und Ihre erste Pull-Anfrage gemäß dem Gitrust-Workflow senden (~90 Min.)