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