Configuration initiale de Forgejo

Après l’installation, Forgejo est fonctionnel mais ouvert : n’importe qui peut créer un compte et les fichiers de configuration ne sont pas encore protégés. Cette page couvre les réglages indispensables avant de mettre votre instance en production.

La configuration de Forgejo repose sur un fichier INI : /etc/forgejo/app.ini. Vous pouvez le modifier directement (après avoir arrêté le service) ou passer par l’interface “Administration du site”.

Comprendre app.ini

app.ini est divisé en sections entre crochets ([server], [database], etc.). Chaque section regroupe les paramètres d’un sous-système. Voici un fichier minimal commenté :

APP_NAME = Mon Instance Forgejo
RUN_USER = git
WORK_PATH = /var/lib/forgejo
RUN_MODE = prod   ; prod ou dev (dev active les logs détaillés)

[database]
DB_TYPE  = sqlite3
PATH     = /var/lib/forgejo/data/forgejo.db

[server]
SSH_DOMAIN       = git.exemple.com
DOMAIN           = git.exemple.com
HTTP_PORT        = 3000
ROOT_URL         = https://git.exemple.com/
OFFLINE_MODE     = true
LFS_START_SERVER = true

[service]
DISABLE_REGISTRATION = true   ; Désactiver les inscriptions publiques

[log]
MODE  = file
LEVEL = Info

Toujours modifier via un éditeur en tant que root

Ne jamais modifier app.ini directement sous l’utilisateur git. Utilisez sudo :

sudo systemctl stop forgejo.service
sudo nano /etc/forgejo/app.ini
sudo systemctl start forgejo.service

Opérations de configuration essentielles

1. Désactiver les inscriptions publiques

Par défaut, Forgejo permet à n’importe qui de créer un compte. Sur une instance interne, désactivez cette option immédiatement.

[service]
DISABLE_REGISTRATION = true

Si vous avez besoin d’inviter des utilisateurs ponctuellement sans ouvrir les inscriptions, activez les tokens d’invitation :

[service]
DISABLE_REGISTRATION        = true
ALLOW_ONLY_INTERNAL_REGISTRATION = false

L’administrateur peut alors créer des liens d’invitation dans Administration > Utilisateurs.

2. Configurer le serveur HTTP et SSH

Ajustez les paramètres [server] pour correspondre à votre domaine réel :

[server]
# Domaine utilisé pour les URLs de clonage SSH
SSH_DOMAIN   = git.exemple.com
# Domaine pour les liens HTTPS
DOMAIN       = git.exemple.com
# URL complète (avec slash final obligatoire)
ROOT_URL     = https://git.exemple.com/
HTTP_PORT    = 3000
OFFLINE_MODE = true
# Activer le stockage Git LFS
LFS_START_SERVER = true
LFS_JWT_SECRET   = <généré automatiquement à l'init>

Cohabitation SSH avec sshd

Si votre serveur utilise déjà le port 22 pour SSH (accès administrateur), vous avez deux options :

Option A — Forgejo sur un port SSH alternatif :

[server]
SSH_PORT        = 2222
SSH_LISTEN_PORT = 2222

Les utilisateurs cloneront avec git clone ssh://git@exemple.com:2222/user/repo.git.

Option B — Pass-through SSH (Gitea/Forgejo built-in SSH proxy) : Forgejo intègre un serveur SSH interne qui peut cohabiter avec sshd. Voir la documentation officielle Forgejo pour les options START_SSH_SERVER et SSH_LISTEN_PORT.

3. Configurer l’envoi d’emails

Sans configuration mailer, Forgejo ne peut pas envoyer les emails de confirmation ou de réinitialisation de mot de passe.

SMTP standard

[mailer]
ENABLED      = true
FROM         = "Forgejo <noreply@exemple.com>"
PROTOCOL     = smtp+starttls
SMTP_ADDR    = smtp.exemple.com
SMTP_PORT    = 587
USER         = noreply@exemple.com
PASSWD       = votre-mot-de-passe

Pas d'email (lab/test)

[mailer]
ENABLED = false

Dans ce cas, les nouvelles inscriptions doivent être activées manuellement par l’administrateur dans Administration > Utilisateurs.

4. Sécuriser les fichiers de configuration

Après toute modification de app.ini, vérifiez que les permissions restent correctes :

sudo chmod 750 /etc/forgejo
sudo chmod 640 /etc/forgejo/app.ini
sudo chown root:git /etc/forgejo
sudo chown git:git /etc/forgejo/app.ini

Secrets dans app.ini

app.ini contient des secrets générés à l’installation (INTERNAL_TOKEN, JWT_SECRET, SECRET_KEY). Une permission 644 exposerait ces valeurs à tous les utilisateurs du système. La permission 640 (lecture root et git uniquement) est le minimum requis.

Gestion des utilisateurs en ligne de commande

Quand l’interface web n’est pas accessible (après un verrouillage ou pour l’automatisation), la CLI Forgejo permet de gérer les utilisateurs.

Pattern CLI Forgejo

Toutes les commandes CLI nécessitent les flags -w (workpath) et -c (config). Exécutez-les toujours avec l’utilisateur git via sudo -u git :

sudo -u git forgejo <commande> \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini

Créer un utilisateur administrateur

sudo -u git forgejo admin user create \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini \
  --username forgejoadmin \
  --password "VotreMotDePasse!" \
  --email admin@exemple.com \
  --admin

Réinitialiser un mot de passe

sudo -u git forgejo admin user change-password \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini \
  --username forgejoadmin \
  --password "NouveauMotDePasse!"

Lister les utilisateurs

sudo -u git forgejo admin user list \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini

Configuration via l’interface web d’administration

Les paramètres modifiables sans toucher à app.ini sont accessibles dans Administration du site (icône d’engrenage en haut à droite) :

Chemin	Paramètre
Administration > Paramètres	Mode d’inscription, taille max des dépôts
Administration > Utilisateurs	Créer, désactiver, promouvoir administrateur
Administration > Organisations	Gérer les organisations
Administration > Hooks	Gits hooks globaux
Administration > Tâches de maintenance	Nettoyer le cache, regénérer les hooks

Glissez pour voir

Personnaliser l’interface (optionnel)

Forgejo supporte la personnalisation via le répertoire custom/ :

# Créer le répertoire de personnalisation
sudo mkdir -p /var/lib/forgejo/custom/templates
sudo chown -R git:git /var/lib/forgejo/custom/

Pour remplacer un template, copiez-le depuis les sources de Forgejo dans custom/templates/ avec le même chemin relatif. Les surcharges CSS vont dans custom/public/css/.

Dépannage

Le service démarre mais l’interface affiche une erreur

sudo journalctl -u forgejo.service -n 50 --no-pager

Pour augmenter le niveau de log temporairement, ajoutez dans app.ini :

[log]
LEVEL = Debug

Redémarrez, reproduisez l’erreur, puis repassez à Info.

ROOT_URL mal configurée

Si les liens dans les emails ou les URLs de clonage sont incorrects, vérifiez :

sudo grep ROOT_URL /etc/forgejo/app.ini

La valeur doit correspondre exactement à l’URL publique de votre instance, avec le slash final : https://git.exemple.com/.

À retenir

• Toute modification de app.ini nécessite un redémarrage du service
• DISABLE_REGISTRATION = true est indispensable sur une instance non publique
• Le pattern CLI Forgejo : sudo -u git forgejo <cmd> -w /var/lib/forgejo -c /etc/forgejo/app.ini
• Les permissions correctes : /etc/forgejo en 750, app.ini en 640
• ROOT_URL doit correspondre exactement à l’URL publique (slash final compris)

Prochaines étapes

Sauvegarder et restaurer Forgejo Mettre en place des sauvegardes automatiques avec forgejo dump.

Mettre à jour Forgejo Procédure d'upgrade sécurisée avec flush-queues et doctor check.

×

📖 Voir la documentation →