2.4 : Premier démarrage : assistant, compte administrateur et réglages

Le moment est venu

Votre forge est publiée sous son nom définitif, en HTTPS. Vous pouvez maintenant ouvrir :

https://forge.nordika.local

Forgejo n’affiche pas une page de connexion, mais un assistant d’installation : une page unique, assez longue, qui va écrire /data/gitea/conf/app.ini et créer la base de données.

Accédez-y impérativement par ce nom, pas par l’IP ni par le port 3000. L’assistant pré-remplit plusieurs champs à partir de l’adresse utilisée, dont l’URL publique. C’est la raison pour laquelle nous l’avons laissé en attente depuis deux leçons.

Un indice qui ne trompe pas : si le champ « Hidden email domain » affiche noreply.localhost, c’est que Forgejo ne connaît pas encore son domaine. Vérifiez DOMAIN dans votre compose avant d’aller plus loin.


Écran 1 — Base de données

Tous les champs sont déjà remplis. C’est normal : ils proviennent des variables FORGEJO__database__* du compose.

Champ Valeur attendue
Database type PostgreSQL
Host db:5432
Username / Password / Database name forgejo
SSL Disable
Schema (vide)

Ne modifiez rien. Toute valeur saisie ici serait de toute façon réécrite par les variables d’environnement au prochain redémarrage.

Le SSL: Disable peut surprendre. Il est légitime ici : la connexion entre Forgejo et PostgreSQL ne quitte jamais le réseau Docker privé forgejo, qui n’est joignable par aucun autre conteneur. Chiffrer ce trajet n’apporterait rien. Si votre base était sur une machine distincte, la réponse serait différente.


Écran 2 — Réglages généraux

C’est ici que se prennent les décisions.

Champ Ce que je recommande Pourquoi
Instance title Forge Nordika S’affiche dans le titre de chaque page. Autant qu’il désigne votre organisation.
Instance slogan (vide) Le slogan par défaut est celui du projet Forgejo.
Repository root path Laisser Sous /data, donc dans votre sauvegarde.
Git LFS root path Laisser Voir la note ci-dessous.
User to run as git Ne pas toucher.
Server domain forge.nordika.local Doit correspondre à votre DOMAIN.
SSH server port Vider le champ Voir ci-dessous.
HTTP listen port 3000 Port interne au conteneur, pas celui vu par les utilisateurs.
Base URL https://forge.nordika.local/ ⚠️ Le champ le plus important de la page.
Log path Laisser
Disable self-registration ✅ Cocher
Enable update checker À vous Voir ci-dessous.

Le port SSH : videz-le

L’aide du champ le dit explicitement : laisser vide pour désactiver le serveur SSH. C’est cohérent avec le choix fait en 2.1 — tout se passera en HTTPS avec des jetons d’accès.

Si vous laissez 22 alors qu’aucun port SSH n’est publié, l’interface proposera des URL de clonage en SSH qui échoueront systématiquement. Vos utilisateurs perdront du temps sur une fonctionnalité qui n’existe pas.

La Base URL : le champ à ne pas rater

C’est l’équivalent de ROOT_URL. Il détermine toutes les URL générées par Forgejo : liens de clonage, liens dans les courriels, redirections d’authentification.

Il doit contenir l’adresse exacte que tapent vos utilisateurs, protocole compris et barre oblique finale incluse. Si vous avez accédé à l’assistant par le bon nom, il est déjà correct — vérifiez-le quand même.

Désactiver l’inscription libre : non négociable

Cochez cette case. Sans elle, n’importe qui atteignant la forge peut créer un compte.

Sur une instance interne, cela signifie que tout collaborateur — ou toute personne ayant accès au réseau — peut s’inscrire et voir vos dépôts publics internes. Les comptes seront créés par vous, ou automatiquement par l’annuaire à partir de la leçon 2.5.

Correspondance : [service] DISABLE_REGISTRATION = true.

Le vérificateur de mises à jour

Il interroge périodiquement un enregistrement DNS TXT chez release.forgejo.org pour signaler les nouvelles versions.

Utile — c’est ainsi que vous saurez qu’un correctif de sécurité est disponible. Mais c’est aussi une requête sortante depuis votre forge, ce qui peut poser question dans un environnement cloisonné. À vous de trancher ; si vous le désactivez, mettez en place une autre veille, parce que ne pas suivre les versions d’un service de production n’est pas une option.

Une note sur Git LFS

Le chemin est proposé, mais le serveur LFS est désactivé par défaut ([server] LFS_START_SERVER = false). LFS permet de stocker des fichiers volumineux hors de l’historique Git.

Pour nos usages — scripts, configurations, YAML — vous n’en aurez pas besoin. Nous en reparlerons en section 5, au moment d’aborder ce que Git ne sait pas bien faire.


Écran 3 — Courriel

Section repliée par défaut. Ouvrez-la : une forge qui ne sait pas envoyer de courriels est une forge muette — pas de notification de pull request, pas de réinitialisation de mot de passe, pas d’alerte.

Champ Exemple
SMTP host smtp.intranet-nordika.fr
SMTP port 25
Send email as [email protected]
SMTP username / password (vides)

Le piège de l’authentification SMTP

Voici un point que la documentation signale et que presque personne ne connaît : Forgejo n’accepte l’authentification SMTP que si la connexion est chiffrée par TLS, ou si le serveur est localhost.

C’est une protection délibérée des bibliothèques Go contre les attaques par dégradation de TLS. Conséquence pratique : un couple identifiant / mot de passe sur le port 25 en clair ne fonctionnera pas, quelle que soit la configuration de votre serveur de messagerie.

Trois configurations valides :

Situation Port Protocole Authentification
Relais interne anonyme 25 (déduit) Aucune — le relais autorise l’IP
STARTTLS 587 smtp+starttls Possible
SMTPS 465 smtps Possible

En entreprise, le premier cas est de loin le plus fréquent : votre serveur de messagerie relaie sans authentification les machines internes autorisées. Laissez alors les champs identifiant et mot de passe vides — c’est correct, ce n’est pas un oubli.

Si vous devez tout de même authentifier, utilisez le port 587 ou 465, et pensez à PASSWD_URI (vu en 2.2) plutôt que d’écrire le mot de passe dans le compose.

Les deux cases en dessous

Require email confirmation to register — sans objet, puisque l’inscription libre est désactivée.

Enable email notifications — cochez-la si vous voulez que les utilisateurs soient prévenus des tickets et des pull requests. Correspond à [service] ENABLE_NOTIFY_MAIL = true. Utile dès la section 4, quand vous ferez relire une modification.

Tester après coup

L’assistant ne teste pas la configuration. Une fois l’installation terminée, allez dans Administration du site → Configuration → Configuration du serveur de messagerie : un bouton permet d’envoyer un courriel de test. Faites-le tout de suite, pendant que vous avez le contexte en tête.


Écran 4 — Serveur et services tiers

Quelques options méritent votre attention.

Enable local mode ✅ — sert toutes les ressources depuis votre serveur au lieu de réseaux de distribution externes. À garder activé sur une instance interne : votre forge doit fonctionner même sans accès Internet.

Disable Gravatar ✅ — évite d’envoyer une empreinte de l’adresse de vos utilisateurs à un service tiers pour afficher un avatar. Sur une instance d’entreprise, c’est le bon réglage.

Enable OpenID sign-in — ⚠️ attention au faux ami. Cette option concerne OpenID 2.0, un protocole ancien qui n’a rien à voir avec OpenID Connect. Si vous prévoyez de brancher Keycloak, Authentik ou Entra ID, ce n’est pas ici que ça se passe : cela se configurera en leçon 2.6, via les sources d’authentification. Vous pouvez décocher sans crainte.

Require to sign-in to view instance content — force la connexion pour consulter quoi que ce soit, y compris les dépôts publics. Ne le cochez pas tout de suite : ce réglage a des conséquences directes sur le mécanisme de distribution par GPO de la section 7, et nous en discuterons en 2.9.

Hide email addresses by default — à cocher si vous ne souhaitez pas que les adresses soient visibles dans l’interface.

Allow creation of organizations by default — laissez pour l’instant, nous structurerons cela en 2.8.

Hidden email domain — remplacez noreply.localhost par noreply.nordika.fr. C’est le domaine qui apparaîtra dans l’historique Git pour les utilisateurs ayant choisi de masquer leur adresse.


Écran 5 — Le compte administrateur

L’assistant précise que ce compte est optionnel, le premier inscrit devenant administrateur. Créez-le quand même : sur une instance où l’inscription libre est désactivée, ne pas le faire vous laisserait sans porte d’entrée.

Reste une vraie question, et elle mérite mieux qu’un réflexe.

Compte nominatif ou compte dédié ?

La tentation est de saisir votre propre identité : romain.dupont, votre adresse professionnelle. C’est naturel, et c’est ce que fait tout le monde.

Je vous recommande plutôt de créer ici un compte d’administration dédié, du type admin-local, avec une adresse de service.

La raison tient en une phrase : dès la leçon 2.6, vos utilisateurs se connecteront via l’annuaire ou le fournisseur d’identité. Le jour où celui-ci sera indisponible, il vous faudra un compte purement local pour entrer.

Ce n’est pas un scénario théorique. Un contrôleur de domaine qui ne répond plus, un certificat d’IdP expiré, une mauvaise manipulation dans la configuration OIDC : dans les trois cas, si votre seul compte administrateur dépend de l’authentification externe, vous êtes enfermé dehors — de votre propre forge, celle dont dépendent vos GPO et vos déploiements.

La bonne pratique est donc :

  1. Un compte d’administration local dédié, créé ici, avec un mot de passe long, stocké dans votre coffre-fort, et utilisé uniquement en cas de besoin.
  2. Votre compte nominatif, créé ensuite — ou fourni automatiquement par l’annuaire — pour votre travail quotidien.

C’est exactement le principe du compte de secours que vous appliquez déjà sur vos équipements réseau et vos hyperviseurs. Il n’y a aucune raison d’y déroger ici.

À protéger comme tel : ce compte doit avoir un mot de passe unique et robuste, et faire l’objet d’une double authentification dès que possible. Il ouvre l’accès à un service qui distribuera du code exécuté sur vos postes.


Valider

Cliquez sur Install Forgejo. La page indique qu’elle écrira la configuration dans /data/gitea/conf/app.ini.

Le démarrage prend quelques secondes — l’écran de chargement est normal. Forgejo crée le schéma de la base, génère ses clés secrètes, puis affiche l’accueil.

Deux choses se sont produites en arrière-plan :

app.ini a été écrit. Vous pouvez le consulter :

docker compose exec forge-server cat /data/gitea/conf/app.ini

Vous y retrouverez les valeurs de vos variables d’environnement, plus celles saisies dans l’assistant.

INSTALL_LOCK est passé à true dans la section [security]. La page d’installation n’est plus accessible — c’est le comportement attendu.

Une clé secrète a été générée (SECRET_KEY). Elle protège notamment les secrets de double authentification. Sa perte les rend irrécupérables. Elle vit dans app.ini, donc dans le dossier /data — nous la traiterons en section 14, mais retenez qu’elle fait partie intégrante de votre sauvegarde.


Les réglages à ajouter maintenant

L’assistant ne propose pas tout. Voici cinq ajouts que je vous conseille de faire tout de suite, dans le compose, avant que la forge ne se remplisse.

# Sécurité
- FORGEJO__security__GLOBAL_TWO_FACTOR_REQUIREMENT=admin
- FORGEJO__security__REVERSE_PROXY_TRUSTED_PROXIES=172.16.0.0/12
- FORGEJO__security__LOGIN_REMEMBER_DAYS=365

# Dépôts privés par défaut
- FORGEJO__repository__DEFAULT_PRIVATE=private

# Cache adapté aux petites instances
- FORGEJO__cache__ADAPTER=twoqueue
- FORGEJO__cache__HOST={"size":100,"recent_ratio":0.25,"ghost_ratio":0.5}

La double authentification pour les administrateurs est le réglage le plus important de cette liste. Votre forge distribuera bientôt du code exécuté avec des privilèges élevés sur vos postes ; un compte administrateur compromis est un vecteur d’exécution de code sur tout le parc.

DEFAULT_PRIVATE=private fait que tout nouveau dépôt naît privé. On peut le rendre public ensuite, en connaissance de cause — l’inverse est nettement moins confortable. Il existe aussi FORCE_PRIVATE=true, qui interdit purement et simplement les dépôts publics ; à réserver aux instances où le pattern GPO de la section 7 n’est pas prévu.

Le cache twoqueue est la recommandation officielle pour les instances à faible activité : le cache par défaut conserve jusqu’à 50 000 éléments pendant seize heures, ce qui est disproportionné pour une forge d’entreprise. Le réglage ci-dessus le ramène à une taille raisonnable.

Redémarrez pour appliquer :

docker compose up -d

La variante : se passer complètement de l’assistant

Vous avez maintenant vu ce que l’assistant configure. Il existe une autre voie, plus cohérente avec l’esprit de cette formation.

En déclarant toute la configuration dans le compose et en ajoutant :

- FORGEJO__security__INSTALL_LOCK=true

la page d’installation devient inaccessible et Forgejo démarre directement, prêt à l’emploi. Il ne reste qu’à créer le compte administrateur en ligne de commande :

docker compose exec -u git forge-server \
  forgejo admin user create \
    --username admin-local \
    --email [email protected] \
    --password 'un-mot-de-passe-long' \
    --admin

(Vérifiez les options disponibles sur votre version avec forgejo admin user create --help — notamment celles concernant le changement de mot de passe au premier accès.)

Pourquoi c’est intéressant

Votre forge devient entièrement décrite par un fichier. Un docker-compose.yml versionné, un .env au coffre, et vous pouvez la redéployer à l’identique — sur une nouvelle VM, dans un environnement de test, ou après un incident.

C’est précisément le pattern ① de la carte, appliqué à la forge elle-même. Il y a une certaine élégance à ce que l’outil qui va versionner votre infrastructure soit lui-même décrit dans un dépôt.

Un mot de passe en clair dans une ligne de commande reste à éviter : il atterrit dans l’historique du shell. Passez par une variable d’environnement, ou changez-le immédiatement après création.

Je vous conseille de faire l’assistant une fois, pour comprendre, puis d’adopter cette approche quand vous redéploierez pour de bon.


Vérifier

Quatre contrôles avant de passer à la suite.

L’URL de clonage. Créez un dépôt de test : l’adresse proposée doit être https://forge.nordika.local/..., sans port ni localhost, et sans proposition SSH.

Le courriel. Administration du site → Configuration → envoyez un test.

L’inscription. Déconnectez-vous : aucun bouton d’inscription ne doit apparaître.

L’adresse d’origine dans les journaux. Comme en 2.3, vérifiez que vous voyez l’IP de votre poste et non celle du proxy.


Ce qu’il faut retenir

  • Accédez à l’assistant par le nom définitif : il fige l’URL publique.
  • Les champs de base de données sont pilotés par le compose : n’y touchez pas.
  • Videz le port SSH si vous travaillez uniquement en HTTPS.
  • Désactivez l’inscription libre, systématiquement.
  • L’authentification SMTP exige TLS : sur le port 25, laissez identifiant et mot de passe vides.
  • « Enable OpenID sign-in » n’est pas OpenID Connect — Keycloak et consorts se configurent en 2.6.
  • Créez un compte d’administration local dédié, distinct de votre compte nominatif : c’est votre porte de secours le jour où l’annuaire tombe.
  • SECRET_KEY est générée à l’installation et fait partie de votre sauvegarde.
  • Ajoutez la double authentification pour les administrateurs et les dépôts privés par défaut avant de commencer à travailler.
  • INSTALL_LOCK=true permet de décrire toute la forge dans un fichier versionnable.

Dans la leçon suivante

Votre forge fonctionne, avec un unique compte administrateur. Il est temps de la raccorder à votre annuaire.

Nous configurerons l’authentification LDAP / Active Directory : synchronisation des comptes, filtres pour ne remonter que les groupes concernés, mise en correspondance des attributs, et le point sur lequel tout le monde se casse les dents — le compte de service de lecture et ses permissions.

Ce sera aussi l’occasion de comprendre pourquoi la connexion à l’interface web et les opérations Git suivent deux chemins d’authentification totalement distincts.

📎 Ressources 1