Premier démarrage : bootstrap admin, clé SSH hôte et vérification santé¶

Objectifs¶

À la fin de ce tutoriel, vous saurez :

• O1. Expliquer comment gitrust crée automatiquement le compte administrateur initial à partir des variables ADMIN_*
• O2. Identifier et vérifier la clé SSH hôte Ed25519 générée automatiquement au premier démarrage
• O3. Confirmer que les trois services (HTTP :4000, SSH :2222, PostgreSQL :5432) sont sains via des commandes de vérification
• O4. Vous connecter à l'interface d'administration /admin pour la première fois

Pré-requis¶

• Technique : gitrust installé et démarré via 01-installation-docker ou 02-installation-systemd ; curl, ssh-keyscan, psql disponibles
• Pédagogique : Tutoriel 01 ou 02 complété — gitrust doit être active (running)
• Temps estimé : ~20 minutes

Vue d'ensemble¶

Le premier démarrage de gitrust effectue automatiquement trois opérations critiques, dans cet ordre :

sequenceDiagram
    participant S as systemd / Docker
    participant G as gitrust (binaire)
    participant PG as PostgreSQL
    participant FS as Système de fichiers

    S->>G: ExecStart / docker run
    G->>PG: Connexion DATABASE_URL
    G->>PG: AppMigrator::run_migrations()
    PG-->>G: Migrations OK (18 tables créées)
    G->>FS: SSH_HOST_KEY_PATH absent ?
    FS-->>G: Absent
    G->>FS: Génère Ed25519 host key
    G->>PG: ensure_default_admin() — users vide ?
    PG-->>G: Vide
    G->>PG: INSERT admin (ADMIN_USERNAME, ADMIN_EMAIL, hash(ADMIN_PASSWORD))
    G-->>S: Listening on :4000 (HTTP) et :2222 (SSH)

Modèle mental : c'est le même principe qu'un routeur domestique — à la première mise sous tension, il crée un mot de passe admin par défaut (ici fourni par vous via .env) et ne recommence jamais s'il existe déjà des données.

Étape 1 : Vérifier les migrations automatiques¶

Les migrations sont appliquées à chaque démarrage, mais seulement si elles n'ont pas encore été jouées. Elles sont idempotentes.

Consultez les logs :

# Installation systemd
sudo journalctl -u gitrust --since "10 minutes ago" --no-pager | grep -E "migrat|admin|listen"

# Installation Docker
docker compose logs gitrust 2>&1 | grep -E "migrat|admin|listen"

Sortie attendue (premier démarrage) :

INFO gitrust_core::migrations: Running migrations...
INFO gitrust_core::migrations: Applied migration m20260305_000001_initial_schema
INFO gitrust_core::migrations: Applied migration m20260306_000002_create_app_settings_table
...
INFO gitrust_core::migrations: Applied migration m20260327_000013_create_pr_comments
INFO gitrust_core::migrations: All migrations applied successfully (18 applied)
INFO rustwarden_core::services::default_admin_service: Admin user 'admin' created
INFO gitrust_web: HTTP server listening on 127.0.0.1:4000
INFO gitrust_ssh: SSH server listening on 0.0.0.0:2222

Sortie attendue (démarrage suivant) :

INFO gitrust_core::migrations: Running migrations...
INFO gitrust_core::migrations: No pending migrations

Checkpoint O1 : si vous voyez Admin user 'admin' created, le bootstrap admin a fonctionné. Si vous voyez Admin user already exists, skipping, un compte admin existait déjà — c'est normal si ce n'est pas le tout premier démarrage.

Étape 2 : Vérifier la clé SSH hôte¶

gitrust génère une clé Ed25519 à SSH_HOST_KEY_PATH si elle n'existe pas. Cette clé identifie votre instance auprès des clients Git.

Vérifiez que la clé existe :

# Systemd
sudo -u gitrust ls -la /opt/gitrust/data/ssh_host_ed25519_key*

# Docker (le volume est monté dans /data dans le conteneur)
docker compose exec gitrust ls -la /data/ssh_host_ed25519_key*

Sortie attendue :

-rw------- 1 gitrust gitrust  399 ...  /opt/gitrust/data/ssh_host_ed25519_key
-rw-r--r-- 1 gitrust gitrust   93 ...  /opt/gitrust/data/ssh_host_ed25519_key.pub

Affichez le fingerprint SHA256 (à conserver précieusement — vos utilisateurs vérifieront ce fingerprint lors du premier git clone) :

# Systemd
sudo -u gitrust ssh-keygen -l -f /opt/gitrust/data/ssh_host_ed25519_key.pub

# Docker
docker compose exec gitrust ssh-keygen -l -f /data/ssh_host_ed25519_key.pub

Sortie attendue :

256 SHA256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX gitrust-host-key (ED25519)

Important : notez ce fingerprint SHA256 dans votre documentation interne. Vos utilisateurs devront le comparer lors du premier ssh-keyscan ou lors du message The authenticity of host ... can't be established. Si vous régénérez cette clé après que des utilisateurs ont cloné des dépôts, leur ~/.ssh/known_hosts sera en conflit et tous les push/pull échoueront.

Checkpoint O2 : les deux fichiers existent avec les bonnes permissions (clé privée 600, clé publique 644).

Étape 3 : Vérifier la santé des trois services¶

HTTP :4000¶

curl -v http://localhost:4000/ 2>&1 | grep -E "^< HTTP|Location"

Sortie attendue :

< HTTP/1.1 302 Found
< location: /login

Une redirection vers /login signifie que gitrust répond et que le routeur fonctionne.

SSH :2222¶

ssh-keyscan -p 2222 -H localhost 2>/dev/null

Sortie attendue :

[localhost]:2222 ssh-ed25519 AAAA... (votre clé hôte)

Si aucune sortie, le serveur SSH n'écoute pas encore — consultez les logs.

PostgreSQL :5432¶

# Depuis l'hôte
psql "postgres://gitrust:VOTRE_MOT_DE_PASSE@localhost:5432/gitrust" \
  -c "SELECT COUNT(*) AS nb_tables FROM information_schema.tables WHERE table_schema='public';"

Sortie attendue :

 nb_tables
-----------
        18
(1 row)

18 tables = toutes les migrations ont été appliquées.

Checkpoint O3 : les trois commandes répondent comme attendu. Si l'une échoue, consultez la section « Et si ça ne marche pas ».

Étape 4 : Premier accès à l'interface d'administration¶

Ouvrez votre navigateur sur http://VOTRE_SERVEUR:4000/login (ou https:// si vous avez déjà configuré un reverse-proxy TLS).

Connectez-vous avec : - Identifiant : valeur de ADMIN_USERNAME dans votre .env (par défaut : admin) - Mot de passe : valeur de ADMIN_PASSWORD dans votre .env

Après connexion, accédez au tableau de bord d'administration :

http://VOTRE_SERVEUR:4000/admin

Vous devriez voir : - Le nombre d'utilisateurs (1 — l'admin initial) - Le nombre de dépôts (0) - L'état des services CI

Sécurité : changez immédiatement le mot de passe admin via /admin/users ou le profil utilisateur si vous avez utilisé un mot de passe faible dans .env. Ensuite, vous pouvez supprimer ou commenter ADMIN_PASSWORD dans .env — gitrust ne recrée le compte admin que si la table users est vide.

Checkpoint O4 : vous êtes connecté à /admin et le tableau de bord s'affiche sans erreur.

Récapitulatif¶

• ✓ O1 accompli en lisant les logs de démarrage qui confirment les migrations et la création du compte admin
• ✓ O2 accompli en vérifiant l'existence et le fingerprint SHA256 de la clé SSH hôte Ed25519
• ✓ O3 accompli en testant HTTP (:4000 → 302), SSH (:2222 → fingerprint) et PostgreSQL (:5432 → 18 tables)
• ✓ O4 accompli en se connectant à /admin avec les identifiants ADMIN_* du .env

Et si ça ne marche pas¶

Prochaine étape¶

→ 04 — Mise en production : reverse-proxy TLS, SMTP, sauvegarde

Ou, si vous voulez configurer les fonctionnalités avancées maintenant : - Configurer SMTP - Configurer OAuth - Sauvegarder l'instance