Iniziare con gitrust: compila, configura e invia il tuo primo 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 »).

Obiettivi

Al termine di questo tutorial saprai:

  • O1. Compila gitrust dal sorgente e avvia l'istanza di sviluppo localmente
  • O2. Configura l'ambiente di sviluppo (database, variabili di ambiente, risorse CSS)
  • O3. Esegui un primo push SSH sulla tua istanza locale e controlla il risultato nell'interfaccia web

Prerequisiti

  • Tecnico: Rust stable ≥ 1.80 (rustc --version), PostgreSQL ≥ 15 (psql --version), Node.js ≥ 18 (node --version), Git 2.x (git --version), Docker (opzionale, consigliato per il database)
  • 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
  • Tempo stimato: ~45 minuti

Panoramica

Prima di eseguire il primo comando, prendiamoci 3 minuti per capire cosa andremo ad assemblare e come si incastreranno le parti.

gitrust è un monorepo Rust a 6 casse che viene compilato in un singolo binario. Quando esegui cargo run, questo binario avvia due server contemporaneamente: un server HTTP (:4000) per l'interfaccia web e l'API REST e un server SSH (:2222) per le operazioni git push/pull. Condividono lo stesso database PostgreSQL e l'archiviazione del repository su disco nudo.

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

Cosa farai: clonare i sorgenti → preparare PostgreSQL → copiare e compilare .env → compilare le risorse CSS → eseguire cargo run → controllare l'istanza → inviare un primo commit tramite SSH.

Passaggio 1: verificare i requisiti di sistema

Prima di clonare qualsiasi cosa, assicurati di avere tutti gli strumenti necessari installati:

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

Output previsto (le versioni esatte possono variare): 

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

Se mancano delle dipendenze di sistema, installale:

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

# macOS
brew install postgresql openssl cmake

Checkpoint: tutti i comandi di controllo devono restituire un numero di versione privo di errori. Se rustc non viene trovato, installa Rust tramite curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh quindi ricarica la shell.

Passaggio 2: clona il progetto

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

Risultato previsto: 

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: verificare che sia presente la struttura della cassa:

ls crates/

Risultato previsto: 

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

Passaggio 3: configurare l'ambiente (.env)

Copia il file di esempio e modifica i 5 valori essenziali:

cp .env.example .env

Apri .env nel tuo editor e inserisci questi valori:

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

Genera un valore reale per JWT_SECRET:

openssl rand -hex 32

Risultato previsto (valore diverso per ogni esecuzione): 

4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Copia questo valore in .env per JWT_SECRET.

Checkpoint: controlla che nessun valore di esempio rimanga in .env:

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

Il comando dovrebbe restituire vuoto (nessuna riga). Se restituisce righe, i valori segnaposto sono ancora presenti: l'applicazione verrà avviata ma con una configurazione non sicura.

Passaggio 4: preparare il database PostgreSQL

Hai due opzioni:

Opzione A — Docker (consigliata per i principianti):

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

Risultato previsto: 

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

Opzione B: PostgreSQL esistente sulla macchina:

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

Risultato previsto: 

CREATE ROLE
CREATE DATABASE

Adattare la password in DATABASE_URL in .env se si utilizza l'opzione B.

Checkpoint: verifica che la base sia accessibile dall'applicazione:

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

Risultato previsto: 

                                                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)

Se ricevi "psql: errore: connessione al server non riuscita", controlla che PostgreSQL sia in esecuzione e che "DATABASE_URL" corrisponda.

Passaggio 5: compila le risorse CSS

gitrust utilizza Tailwind CSS + DaisyUI. Le risorse devono essere compilate localmente: niente CDN, tutti i file vengono serviti da static/:

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

Risultato previsto: 

added 98 packages in 3s

Rebuilding...
Done in 1842ms.

Checkpoint: verifica che il file CSS sia generato:

ls -lh static/css/style.css

Risultato previsto: 

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

Se il file è di 0 byte o non esiste, la compilazione non è riuscita: esegui nuovamente npm install e poi il comando npx tailwindcss.

Passaggio 6: avvia l'app

cargo run

La prima compilazione richiede 2-5 minuti (tutte le dipendenze vengono compilate). Le compilazioni successive sono incrementali e molto più veloci.

Au premier lancement, gitrust exécute automatiquement : 1. Migrazioni del database (creazione di tutte le tabelle) 2. Creazione dell'account amministratore (da .env) 3. Generazione della chiave host SSH (data/ssh_host_ed25519_key) 4. Creazione della directory di archiviazione del repository (data/repos/)

Output previsto (dopo la compilazione): 

   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: apri http://localhost:4000 nel tuo browser. Devi vedere la home page di gitrust. Accedi con le credenziali ADMIN_USERNAME / ADMIN_PASSWORD definite in .env. Se la pagina non si carica, controlla che nei log venga visualizzato il messaggio Server in ascolto su http://0.0.0.0:4000.

Passaggio 7: crea un repository e invia il tuo primo commit

Nell'interfaccia web (http://localhost:4000), fare clic su “Nuovo repository”, assegnare un nome (ad esempio mio-progetto) e fare clic su Crea.

Aggiungi la tua chiave SSH pubblica in Impostazioni > Chiavi SSH incollando il contenuto di ~/.ssh/id_ed25519.pub.

Quindi nel tuo terminale:

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

Risultato previsto: 

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: torna al browser su http://localhost:4000/admin/my-project. La pagina dovrebbe visualizzare il file "README.md" con il contenuto "#My project" e indicare 1 commit sul ramo "main".

Funzionalità aggiuntive disponibili

IC integrato (opzionale)

Il CI viene eseguito su un server di build tramite SSH + rsync. Configura 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

Modalità facile: aggiungi .gitrust-ci.yml alla radice del tuo repository:

language: rust

build:
  command: "cargo build --release"

tests:
  command: "cargo test"

Modalità di alimentazione: posiziona un modulo Dagger in .dagger/ alla radice. gitrust eseguirà dagger call -m .dagger/ ci.

Notifiche

Configura SMTP in ".env" per le notifiche email:

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

Linguaggio dell'interfaccia

gitrust è disponibile in 6 lingue (fr, en, de, es, pt, it). Imposta la lingua predefinita per l'istanza:

DEFAULT_LOCALE=fr
  • ✓ O1 completato: gitrust è compilato dal sorgente e viene eseguito localmente — cargo run visualizza "Server in ascolto su http://0.0.0.0:4000"
  • ✓ O2 completato: l'ambiente è configurato: .env popolato, PostgreSQL connesso, risorse CSS generate, migrazioni applicate
  • ✓ O3 completato: un primo push SSH ha avuto successo: il commit è visibile nell'interfaccia web su http://localhost:4000/admin/mon-project

E se non funziona

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

Prossimo passo

→ 02 — Primo contributo: clone, build, test, PR: scopri come creare un ramo di funzionalità, scrivere test e inviare la tua prima richiesta pull seguendo il flusso di lavoro gitrust (~90 min)