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

• Paramètres dynamiques /admin/settings — variables modifiables à chaud sans redémarrage
• Tutoriel 02 — Installation systemd — exemple de .env minimal de production
• Configurer ssh-guard — recettes par profil de déploiement
• Événements ssh-guard (JSON) — schéma des événements émis