Variables d'environnement

Référence exhaustive de toutes les variables d'environnement de gitrust. Ces variables se définissent dans le fichier .env (ou .env.production) et sont chargées une seule fois au démarrage. Modifier le fichier sans redémarrer le service n'a aucun effet.

Principe d'autonomie : ce tableau contient intégralement le contenu documenté de .env.example. La documentation ne référence pas le fichier source par lien — tout est ici.

Les variables marquées SEC ont des contraintes de sécurité vérifiées au démarrage : gitrust refuse de démarrer si elles ne sont pas conformes.

1. Base de données

Variable Défaut Obligatoire Description
DATABASE_URL — Oui URL de connexion PostgreSQL. Format : postgres://USER:PASSWORD@HOST:PORT/DB. Le mot de passe doit être fort en production. PostgreSQL ne doit jamais binder sur 0.0.0.0 en production.

Exemples : 

# Développement local (Docker Compose)
DATABASE_URL=postgres://gitrust:gitrust@localhost:5432/gitrust

# Production (réseau privé)
DATABASE_URL=postgres://gitrust:MOT_DE_PASSE_FORT@db.internal:5432/gitrust

2. Serveur HTTP

Variable Défaut Description
SERVER_HOST 0.0.0.0 Adresse d'écoute HTTP. En production derrière un reverse-proxy : 127.0.0.1. En développement : 0.0.0.0.
SERVER_PORT 3000 Port HTTP. Convention gitrust : 4000 en production.

3. Logging

Variable Défaut Description
RUST_LOG debug Niveau de log (syntaxe tracing_subscriber::EnvFilter). Valeurs : error, warn, info, debug, trace. Syntaxe avancée : "info,gitrust_core=debug,sea_orm=warn".

4. Serveur SSH Git

Variable Défaut Description
SSH_HOST_KEY_PATH ./data/ssh_host_ed25519_key Chemin de la clé hôte SSH Ed25519. Générée automatiquement au premier démarrage si absente. SEC : permissions 600, propriétaire = utilisateur systemd. En production : chemin absolu.
SSH_PORT 2222 Port d'écoute du serveur SSH Russh (intégré, distinct de sshd).
SSH_LISTEN_ADDR 0.0.0.0 Adresse d'écoute SSH. 127.0.0.1 si derrière un proxy nginx stream.
SSH_PUBLIC_HOST localhost Nom d'hôte affiché dans les URLs de clone SSH dans l'UI. En production : FQDN public.
MAX_SSH_KEY_SIZE 16384 Taille maximale d'une clé SSH publique acceptée (octets).

5. JWT et authentification

Variable Défaut Description
JWT_SECRET — SEC OBLIGATOIRE — Secret de signature JWT. Minimum 32 bytes. Générer avec openssl rand -hex 64. Les valeurs exemples (change-me-in-production, etc.) sont explicitement rejetées au démarrage. Changer cette valeur invalide toutes les sessions actives.
JWT_EXPIRATION_MINUTES 15 Durée de vie d'un JWT d'accès (minutes).
JWT_ISSUER mon-app Valeur du claim iss dans le JWT. En production : FQDN public.
REFRESH_TOKEN_EXPIRATION_DAYS 7 Durée du refresh token (jours). Rotation à chaque usage.
REMEMBER_ME_EXPIRATION_DAYS 30 Durée étendue quand « Se souvenir de moi » est coché. SEC : doit être ≥ REFRESH_TOKEN_EXPIRATION_DAYS et ≤ 90 jours. Au-delà de 60 jours : warning dans les logs.

6. Sessions

Variable Défaut Description
SESSION_TIMEOUT_MINUTES 30 Timeout d'inactivité d'une session (minutes).
SESSION_BACKEND seaorm Backend de stockage : memory (volatil, dev uniquement), seaorm (PostgreSQL, recommandé), redis (multi-instances, nécessite REDIS_URL).
REDIS_URL — URL Redis (obligatoire si SESSION_BACKEND=redis). Exemple : redis://localhost:6379.

7. Rate limiting

Variable Défaut Description
RATE_LIMIT_LOGIN_PER_MINUTE 5 Tentatives de connexion par IP par minute. Protection contre le brute force.
RATE_LIMIT_REFRESH_PER_MINUTE 10 Rafraîchissements de token par IP par minute.
RATE_LIMIT_GENERAL_PER_MINUTE 100 Limite globale sur tous les autres endpoints. 0 = désactivé (déconseillé).

8. Cookies et debug

Variable Défaut Description
APP_DEBUG false SEC : true = logs verbeux, cookies non sécurisés (HTTP local). false = production, enforce COOKIE_SECURE=true même si défini à false. Ne jamais mettre true en production.
COOKIE_SECURE false Cookies envoyés uniquement via HTTPS. SEC : forcé à true si APP_DEBUG=false.
COOKIE_SAME_SITE Lax Politique SameSite. Strict (le plus sûr, casse les redirections OAuth cross-site), Lax (compatible OAuth), None (nécessite Secure=true).

9. Bootstrap admin initial

Variable Défaut Description
ADMIN_USERNAME admin Nom d'utilisateur du compte admin créé au premier démarrage (si la table users est vide). 3-64 caractères alphanumériques + _-.
ADMIN_EMAIL admin@example.com Adresse e-mail du compte admin initial. Doit contenir @ + domaine avec ..
ADMIN_PASSWORD — SEC OBLIGATOIRE — Mot de passe du compte admin initial. Minimum 8 caractères. À remplacer immédiatement après le premier démarrage.
CREATE_DEFAULT_ADMIN true Mettre à false une fois d'autres admins créés pour désactiver la création automatique.

10. Email SMTP

Variable Défaut Description
SMTP_HOST — Serveur SMTP. Obligatoire pour activer les e-mails. Sans cette variable, gitrust démarre mais les fonctionnalités e-mail sont désactivées.
SMTP_PORT 587 Port SMTP : 25 (non chiffré, interdit en prod), 465 (TLS natif), 587 (STARTTLS, recommandé), 1025 (dev/Mailpit).
SMTP_USER — Identifiant SMTP. Souvent = adresse e-mail expéditrice.
SMTP_PASSWORD — Mot de passe applicatif SMTP (pas le mot de passe du compte e-mail).
SMTP_FROM — Adresse expéditeur. Doit être valide (validée par is_valid_email). En prod : valider DKIM/SPF sur le domaine.
SMTP_FROM_NAME — Nom affiché dans le champ « De : » des e-mails.
SMTP_USE_TLS true Activer TLS natif (port 465).
SMTP_USE_STARTTLS true Activer STARTTLS (port 587). SEC : ne jamais désactiver les deux en production.
SMTP_ACCEPT_INVALID_CERTS false SEC : accepter les certificats SMTP invalides. Warning au démarrage si true. Uniquement pour les serveurs de mail internes en développement.
SMTP_CA_CERT_PATH — Chemin vers un CA personnalisé (PEM) pour valider le certificat SMTP.
EMAIL_BASE_URL http://localhost:3000 URL de base pour les liens dans les e-mails. Obligatoire en prod sinon les liens pointent vers localhost. Doit commencer par http:// ou https://.
EMAIL_QUEUE_BATCH_SIZE 10 Nombre d'e-mails traités par tick du worker.
EMAIL_QUEUE_RETRY_ATTEMPTS 5 Tentatives d'envoi avant abandon.
EMAIL_QUEUE_RETRY_DELAY_SECONDS 300 Délai entre deux tentatives (secondes).
EMAIL_QUEUE_INTERVAL_SECS 30 Intervalle du tick du worker e-mail (secondes).
EMAIL_VALIDATION_REQUIRED true Exiger la validation e-mail à l'inscription. Note : cette variable est documentée dans .env.example mais la valeur effective est contrôlée par le paramètre dynamique validation_email_required en base de données.

11. Inscription

Variable Défaut Description
ALLOW_REGISTRATION false Autoriser l'inscription publique. Note : valeur effective contrôlée par le paramètre dynamique allow_registration en base de données — voir Paramètres dynamiques.

12. Application (branding)

Variable Défaut Description
APP_NAME Mon Application Nom affiché dans l'UI, les e-mails et la balise <title>.
APP_THEME light Thème visuel. Valeurs : light, dark.
DEFAULT_LOCALE fr Langue par défaut. Valeurs : fr, en, de, es, pt, it.

13. IMAP — traitement des bounces (optionnel)

Si IMAP_HOST est vide, la fonctionnalité est désactivée sans erreur.

Variable Défaut Description
IMAP_HOST — Serveur IMAP. Obligatoire pour activer le traitement des bounces.
IMAP_PORT 993 Port IMAP : 993 (TLS direct, recommandé), 143 (STARTTLS).
IMAP_USER = SMTP_USER Identifiant IMAP.
IMAP_PASSWORD = SMTP_PASSWORD Mot de passe IMAP.
IMAP_USE_TLS true TLS direct (port 993).
IMAP_USE_STARTTLS false STARTTLS après connexion (port 143).
IMAP_ACCEPT_INVALID_CERTS false Accepter les certificats invalides (warning si true).
IMAP_MAILBOX INBOX Boîte à scanner pour les bounces.
IMAP_POLL_INTERVAL_SECONDS 300 Intervalle de poll (secondes).
IMAP_SOCKET_TIMEOUT_SECS 30 Timeout socket read/write.

14. Tâches de fond — intervalles et expirations

Ces variables ont des valeurs par défaut raisonnables. Ne les ajustez que si vous avez un besoin spécifique.

Variable Défaut Description
PASSWORD_CHANGE_RETRY_INTERVAL_SECS 600 Retry e-mail changement de mot de passe (10 min).
PASSWORD_CHANGE_RETRY_GAP_MINUTES 20 Espacement minimum entre deux retries.
PASSWORD_CHANGE_MAX_RETRIES 3 Abandon après N échecs.
PASSWORD_CHANGE_CLEANUP_INTERVAL_SECS 86400 Nettoyage quotidien des demandes expirées.
PASSWORD_CHANGE_EXPIRATION_HOURS 24 Validité d'une demande de changement de mot de passe.
PASSWORD_CHANGE_RATE_LIMIT_MAX 3 Demandes maximum par fenêtre.
PASSWORD_CHANGE_RATE_LIMIT_WINDOW_SECS 3600 Fenêtre de rate limit (1 heure).
PASSWORD_RESET_EXPIRATION_HOURS 1 Validité du lien de réinitialisation de mot de passe.
EMAIL_VALIDATION_EXPIRATION_HOURS 24 Validité du lien de validation e-mail.
JWT_CLEANUP_INTERVAL_SECS 3600 Purge de la blacklist JWT expirés.
COOKIE_PREFERENCE_MAX_AGE_SECS 31536000 Durée de vie du cookie de préférences (locale/thème) — 1 an.
PAGINATION_DEFAULT_PER_PAGE 50 Taille par défaut des pages de liste.
PAGINATION_MAX_PER_PAGE 100 Taille maximale des pages de liste.

15. Dépôts Git

Variable Défaut Description
GIT_REPOS_BASE_PATH ./data/repos Chemin des dépôts bare. Structure : {base}/{owner}/{repo}.git. En production : chemin absolu (ex. /opt/gitrust/data/repos). SEC : path traversal bloqué au niveau service.

16. Fichiers statiques

Variable Défaut Description
STATIC_FILES_PATH ./static Chemin du dossier des assets statiques (CSS, JS, images). En production avec systemd : chemin absolu (ex. /opt/gitrust/static).

17. CI/CD Dagger

Variable Défaut Description
CI_ENABLED true Activation globale de la CI. false = plus aucune exécution de pipeline, mais l'UI reste accessible.
CI_DAGGER_BIN dagger Chemin du binaire Dagger. En production : chemin absolu recommandé.
CI_ENGINE_PATH ./deployment/ci-engine Chemin du module CI (Easy Mode — interprète .gitrust-ci.yml).
CI_MAX_CONCURRENT 4 Pipelines exécutés simultanément. Au-delà : file d'attente.
CI_DEFAULT_TIMEOUT 3600 Timeout par défaut d'un pipeline (secondes). Surchargeable par pipeline.
CI_WORKSPACE_PATH /tmp/gitrust-ci Dossier de travail temporaire CI (checkouts, artefacts). En production : /var/lib/gitrust-ci.
CI_LOG_RETENTION_DAYS 30 Rétention des logs de pipeline (jours).

18. Runner CI distant (SSH + rsync)

Variable Défaut Description
CI_REMOTE_HOST localhost Host du runner CI. localhost = CI sur la même machine.
CI_REMOTE_USER $USER Utilisateur SSH sur le runner.
CI_REMOTE_PATH /opt/gitrust-ci Chemin de travail sur le runner.
CI_REMOTE_SSH_KEY — Chemin de la clé privée SSH pour le runner. Optionnel si ssh-agent est chargé.
CI_REMOTE_SSH_PORT 22 Port SSH du runner.

19. Import de dépôts externes

Variable Défaut Description
IMPORT_MAX_CONCURRENT 2 Nombre maximum de clones concurrents.
IMPORT_TIMEOUT_SECS 1800 Timeout par import (secondes). Augmenter pour les gros monorepos.
DB_WORKER_POOL_SIZE 4 Pool de connexions DB dédié au worker d'import. Évite la saturation du pool HTTP principal.

20. SBOM / Dependency-Track

Variable Défaut Description
CI_SBOM_ENABLED false Générer un SBOM (Software Bill of Materials) à chaque pipeline via Syft. Nécessite syft installé.
CI_SYFT_BIN syft Chemin du binaire Syft.
CI_DTRACK_ENABLED false Pousser le SBOM vers Dependency-Track (nécessite CI_SBOM_ENABLED=true).
CI_DTRACK_URL — URL API de Dependency-Track (ex. https://dtrack.internal/api).
CI_DTRACK_API_KEY — Clé API Dependency-Track (générer dans l'UI Dtrack : Administration > API keys).
CI_DTRACK_FRONTEND_URL — URL UI Dependency-Track. Si absent : déduite de CI_DTRACK_URL.

21. OAuth / SSO

Variable Défaut Description
OAUTH_ENCRYPTION_KEY — Clé de chiffrement AES-256-GCM des secrets OAuth en base. Générer avec openssl rand -hex 32.
OAUTH_ENABLED false Activation globale OAuth. Fallback si pas de valeur en base.
OAUTH_REDIRECT_BASE_URL http://localhost:3000 URL de base pour les callbacks OAuth : {URL}/api/v1/auth/oauth/{provider}/callback.
OAUTH_GOOGLE_ENABLED false Activer Google OAuth.
OAUTH_GOOGLE_CLIENT_ID — Client ID Google.
OAUTH_GOOGLE_CLIENT_SECRET — Client Secret Google.
OAUTH_GITHUB_ENABLED false Activer GitHub OAuth.
OAUTH_GITHUB_CLIENT_ID — Client ID GitHub.
OAUTH_GITHUB_CLIENT_SECRET — Client Secret GitHub.
OAUTH_DISCORD_ENABLED false Activer Discord OAuth.
OAUTH_DISCORD_CLIENT_ID — Client ID Discord.
OAUTH_DISCORD_CLIENT_SECRET — Client Secret Discord.
OAUTH_MICROSOFT_ENABLED false Activer Microsoft / Azure AD OAuth.
OAUTH_MICROSOFT_CLIENT_ID — Client ID Azure (Application ID).
OAUTH_MICROSOFT_CLIENT_SECRET — Client Secret Azure.
OAUTH_MICROSOFT_TENANT common Tenant Azure AD : "common" (comptes perso + pro), "organizations" (pro uniquement), ou GUID du tenant.

22. Durcissement SSH (SSH_GUARD_*)

Variables consommées par la crate gitrust-ssh-guard. Toutes sont préfixées SSH_GUARD_. Pour le détail des comportements, voir Configurer ssh-guard et ssh-guard : détection d'attaques SSH.

Modèle de configuration : SSH_GUARD_PROFILE sélectionne un preset cohérent (direct / nginx / haproxy / private / custom). Chaque autre variable override individuellement le défaut du preset.

22.1 Kill switch et profil

Variable Défaut Description
SSH_GUARD_ENABLED true false = pass-through complet, ssh-guard ne fait rien. À éviter sauf urgence.
SSH_GUARD_DRY_RUN false true = les détecteurs tournent et émettent les événements ip_banned, mais aucun ban n'est persisté. Idéal pour valider un nouveau seuil.
SSH_GUARD_PROFILE custom Preset : direct (Internet direct), nginx (derrière nginx stream + PROXY v2), haproxy (derrière HAProxy), private (réseau interne, détecteurs OFF), custom (aucun preset).

22.2 PROXY protocol

Variable Défaut Description
SSH_GUARD_PROXY_PROTOCOL disabled Mode parsing PROXY : disabled, v1 (texte HAProxy legacy), v2 (binaire nginx stream / HAProxy moderne), any (auto-détection v1/v2).
SSH_GUARD_PROXY_PROTOCOL_STRICT true true = drop si en-tête PROXY absent ou invalide quand le mode est activé. false = fallback sur peer_addr avec warn (utile en transition).
SSH_GUARD_PROXY_PROTOCOL_TIMEOUT_MS 3000 Timeout (ms) pour lire l'en-tête PROXY après accept TCP.
SSH_GUARD_TRUSTED_PROXIES — Obligatoire si PROXY activé. Liste CIDR (séparée par virgules) des proxies autorisés à émettre un en-tête PROXY. Sans cette protection, n'importe qui pourrait forger une IP cliente. Exemple : 127.0.0.1/32,::1/128.

22.3 Détecteurs (seuils + fenêtres)

Variable Défaut Description
SSH_GUARD_BRUTE_FORCE_THRESHOLD 5 Nombre d'échecs d'auth depuis une IP avant ban auto. 4294967295 (u32::MAX) = détecteur désactivé.
SSH_GUARD_BRUTE_FORCE_WINDOW_SECS 300 Fenêtre glissante (secondes).
SSH_GUARD_USER_ENUM_THRESHOLD 10 Nombre d'usernames distincts essayés depuis une IP.
SSH_GUARD_USER_ENUM_WINDOW_SECS 300
SSH_GUARD_KEY_SCAN_THRESHOLD 10 Nombre de fingerprints de clé distincts essayés depuis une IP.
SSH_GUARD_KEY_SCAN_WINDOW_SECS 300
SSH_GUARD_CONN_FLOOD_PER_SEC 10 Cap dur de nouvelles connexions TCP par IP par seconde. 0 ou u32::MAX = désactivé.
SSH_GUARD_CONN_FLOOD_BURST 20 Burst autorisé au-dessus du cap soutenu.
SSH_GUARD_MAX_CONCURRENT_PER_IP 10 Limite de sessions concurrentes par IP (placeholder, non encore appliqué).

22.4 Ban

Variable Défaut Description
SSH_GUARD_AUTO_BAN_DURATION_SECS 3600 TTL des bans posés par les détecteurs. 0 = ban permanent.

22.5 Stockage

Variable Défaut Description
SSH_GUARD_STORE_BACKEND hybrid memory (DashMap, perdu au restart), postgres (chaque write en DB), hybrid (RAM chaude + write-through DB + rehydrate au boot — défaut recommandé).
SSH_GUARD_STORE_FLUSH_INTERVAL_MS 1000 Intervalle entre deux flushs RAM → Postgres pour le mode hybrid.
SSH_GUARD_EVENTS_RETENTION_DAYS 90 Rétention de la table ssh_guard_events (utilisée par les détecteurs). Au-delà, les lignes sont purgées.

22.6 Observabilité

Variable Défaut Description
SSH_GUARD_LOG_FORMAT json json (stable, fail2ban-friendly) ou text (debug uniquement).
SSH_GUARD_LOG_TARGET stderr stderr (via tracing → journald), file (fichier dédié uniquement), both (les deux).
SSH_GUARD_LOG_FILE /var/log/gitrust-ssh-guard.json Chemin du fichier dédié si LOG_TARGET=file ou both. Logrotate quasi obligatoire (sinon le fichier grossit sans limite).
SSH_GUARD_METRICS_ENABLED true Expose les métriques Prometheus (placeholder, exposition future).

22.7 Validations bloquantes au démarrage

gitrust refuse de démarrer si :

  • SSH_GUARD_PROXY_PROTOCOL est activé sans SSH_GUARD_TRUSTED_PROXIES (forge d'IP triviale sinon).
  • SSH_GUARD_LOG_TARGET=file ou both sans SSH_GUARD_LOG_FILE valide.

Le message d'erreur identifie la variable fautive.

Récapitulatif local vs production

Dimension Local (dev) Production
DATABASE_URL host localhost Réseau privé
SERVER_HOST 0.0.0.0 127.0.0.1 (derrière nginx)
SERVER_PORT 3000 ou 4000 4000 (nginx devant)
SSH_LISTEN_ADDR 0.0.0.0 127.0.0.1 (nginx stream)
SSH_PUBLIC_HOST localhost FQDN public
COOKIE_SECURE false (HTTP) true (HTTPS, forcé)
APP_DEBUG true false (force sécurité)
EMAIL_BASE_URL http://localhost:... https://FQDN
JWT_SECRET Valeur courte OK openssl rand -hex 64
ADMIN_PASSWORD Faible accepté Fort (≥ 16 caractères)
ALLOW_REGISTRATION true false (instance fermée)
RUST_LOG debug info ou warn
GIT_REPOS_BASE_PATH Relatif (./data) Absolu (/opt/gitrust)

Pour aller plus loin