Installer Forge sur Linux et créer un projet

Accueil Retour

Cette page décrit le parcours complet pour préparer un poste Linux puis créer un nouveau projet Forge.

Elle vise Debian, Ubuntu, Linux Mint et les distributions compatibles avec apt.
Pour les autres distributions, le principe reste le même, seuls les noms de paquets système changent.

---

Objectif

Aller d'un poste Linux propre à un projet Forge qui démarre en développement avec MariaDB.

À la fin de ce parcours, vous disposez :

• des outils système nécessaires ;
• de Forge installé avec pipx ;
• de Git configuré sur le poste ;
• de MariaDB installé et démarré ;
• d'un nouveau projet Forge créé ;
• d'un dépôt Git local versionné et poussé sur GitHub ;
• d'env/dev configuré et cohérent avec MariaDB ;
• de la base initialisée et des migrations appliquées ;
• du serveur de développement lancé.

---

Vue d'ensemble

Cette page est organisée en deux parties.

La première prépare le poste Linux.
Elle se fait une seule fois sur une machine neuve.

La seconde crée et configure un projet Forge.
Elle se refait pour chaque nouveau projet.

Si Forge, Git, pipx et MariaDB sont déjà installés sur votre poste, vous pouvez aller directement à la partie Créer et configurer un projet Forge.

---

Ce que cette page installe

Partie	Domaine	À refaire ?
Préparer le poste Linux	système, pipx, Forge, Git global, MariaDB Server	une fois par machine
Créer et configurer un projet Forge	forge new, env/dev, Git local, GitHub, base MariaDB, migrations, forge run	à chaque nouveau projet

Les pages Préparer MariaDB et Comptes MariaDB d'un projet restent des références pour approfondir ou dépanner.
Vous n'avez pas besoin d'y aller pour terminer une installation standard.

---

Prérequis

• Un poste Linux à jour, avec un accès sudo.
• Une connexion réseau.
• Un compte GitHub si vous souhaitez héberger le dépôt distant.

Mode de lecture

Chaque étape du parcours est placée dans un bloc dépliable.

Ouvrez les étapes dans l'ordre lors d'une première installation.
Pour une vérification ou un dépannage, ouvrez seulement le chapitre concerné.

Les blocs internes indiquent :

• l'objectif de l'étape ;
• les points d'attention ;
• la validation attendue ;
• les erreurs courantes quand elles existent.

---

Partie 1 - Préparer le poste Linux

Cette partie prépare la machine.
Elle se fait une seule fois sur un poste neuf, ou lorsqu'un outil système manque.

1. Mettre à jour le système

Objectif : Mettre à jour les paquets du système avant d'installer Forge et ses dépendances.

sudo apt update
sudo apt upgrade -y

---

Validation attendue

sudo apt update et sudo apt upgrade -y se terminent sans erreur bloquante.

2. Installer les paquets nécessaires

Objectif : Installer les outils système nécessaires à Python, Git, pipx et au connecteur MariaDB.

Attention

Le paquet libmariadb-dev est important : sans lui, l'installation du connecteur Python mariadb peut échouer.

sudo apt install -y \
  python3 \
  python3-venv \
  python3-pip \
  pipx \
  git \
  openssl \
  build-essential \
  python3-dev \
  libmariadb-dev \
  pkg-config

Le paquet libmariadb-dev fournit mariadb_config, requis par le connecteur Python mariadb.
Vérifiez sa présence :

mariadb_config --version

Si cette commande échoue, l'installation de Forge peut échouer avec une erreur du type mariadb_config not found.

---

Validation attendue

mariadb_config --version répond. Si ce n'est pas le cas, le connecteur Python MariaDB risque d'échouer.

3. Activer pipx

Objectif : Rendre la commande pipx disponible dans le terminal courant.

pipx installe la commande forge dans un environnement isolé du Python système.

pipx ensurepath
exec $SHELL -l

Vérifiez que pipx répond :

pipx --version

---

Validation attendue

pipx --version affiche une version.

4. Installer Forge

Objectif : Installer la commande forge depuis PyPI et vérifier qu'elle répond.

Attention

Forge est installé avec --pre parce que la version affichée par cette documentation est une version bêta.

Forge est publié sur PyPI sous la version :

1.0.0rc1

Comme il s'agit d'une version bêta, l'option --pre est transmise à pip :

pipx install --pip-args="--pre" forge-mvc

Vérifiez l'installation :

forge --version

Pour mettre à jour Forge plus tard :

pipx upgrade --pip-args="--pre" forge-mvc

---

Validation attendue

forge --version affiche la version de Forge installée.

5. Configurer Git sur le poste

Objectif : Configurer l'identité Git globale du poste avant la création des commits.

Attention

forge new peut créer un commit initial. Si Git n'a pas d'identité configurée, ce commit peut échouer.

Cette configuration identifie l'auteur des commits sur la machine.
Elle est globale et ne concerne pas encore un projet précis.

forge new crée un commit initial : Git doit donc connaître votre identité, sinon ce commit échoue.

git config --global user.name "Votre Nom"
git config --global user.email "votre.email@example.com"
git config --global init.defaultBranch main

Vérifiez :

git config --global --list

---

Validation attendue

git config --global --list affiche au moins user.name, user.email et init.defaultBranch=main.

6. Installer et démarrer MariaDB

Objectif : Installer MariaDB Server sur le poste et démarrer le service.

MariaDB Server appartient à la préparation du poste.
Il n'a pas besoin d'être réinstallé à chaque projet.

sudo apt install -y \
  mariadb-server \
  mariadb-client

Démarrez MariaDB et activez-le au démarrage de la machine :

sudo systemctl enable --now mariadb

Vérifiez que le service est actif :

systemctl status mariadb --no-pager

---

Validation attendue

systemctl status mariadb --no-pager indique que le service MariaDB est actif.

7. Vérifier l'accès administrateur MariaDB local

Objectif : Vérifier que l'administration locale MariaDB fonctionne avec sudo mariadb.

Sur Debian, Ubuntu et leurs dérivées, l'administration locale se fait souvent avec le compte système root, via sudo.

sudo mariadb

Vous devez obtenir une invite :

MariaDB [(none)]>

Quittez ensuite la console :

exit;

Le compte root MariaDB sert uniquement à l'administration locale via sudo mariadb.
Il ne sert pas à faire tourner l'application.

---

Validation attendue

La console MariaDB [(none)]> s'ouvre avec sudo mariadb.

8. Vérifier que le poste est prêt

Objectif : Contrôler que le poste Linux est prêt pour créer un projet Forge.

Sur le poste, ces commandes doivent répondre :

forge --version
pipx --version
git --version
mariadb_config --version
systemctl status mariadb --no-pager

Si ces commandes fonctionnent, le poste est prêt pour créer des projets Forge.

---

Validation attendue

Les commandes forge, pipx, git, mariadb_config et systemctl status mariadb répondent.

Partie 2 - Créer et configurer un projet Forge

Cette partie se refait pour chaque nouveau projet Forge.

Elle part du principe que le poste Linux est déjà prêt : Forge, Git, pipx et MariaDB sont installés.

1. Créer un nouveau projet Forge

Objectif : Créer un nouveau projet Forge et entrer dans son environnement Python.

Choisissez un nom de projet.
Remplacez NOM_PROJET par votre nom réel, par exemple boutique, blog, welcome-forge ou gestion-stock.

forge new NOM_PROJET
cd NOM_PROJET

forge new prépare un projet complet : squelette, environnement Python, certificat de développement, puis un dépôt Git avec un commit initial.

Activez l'environnement Python du projet :

source .venv/bin/activate

---

Validation attendue

Le dossier du projet existe, l'environnement .venv est activable et le terminal se trouve dans le projet.

2. Lire le fichier env/dev généré

Objectif : Lire les valeurs réelles générées dans env/dev avant toute création de base ou de compte MariaDB.

Attention

Ne recopiez pas les valeurs d'un ancien projet. Chaque projet Forge peut avoir ses propres noms de base et de comptes.

forge new a généré le fichier de configuration de développement :

env/dev

Ce fichier contient les valeurs réelles de votre projet.

Ne déduisez pas les noms MariaDB à partir d'un exemple.
Lisez directement les valeurs générées dans env/dev, en particulier :

• DB_NAME ;
• DB_APP_LOGIN ;
• DB_ADMIN_LOGIN.

Ces valeurs dépendent du projet créé par forge new et doivent être reprises exactement dans les commandes MariaDB.

APP_NAME indique le nom applicatif du projet.

Exemple générique, juste après la création :

APP_NAME=NOM_PROJET
APP_ROUTES_MODULE=mvc.routes

DB_ADMIN_HOST=localhost
DB_ADMIN_PORT=3306
DB_ADMIN_LOGIN=forge_admin
DB_ADMIN_PWD=

DB_NAME=NOM_BASE
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci

DB_APP_HOST=localhost
DB_APP_PORT=3306
DB_APP_LOGIN=NOM_UTILISATEUR_APP
DB_APP_PWD=
DB_POOL_SIZE=5

Points importants :

• DB_ADMIN_LOGIN est le compte d'administration utilisé par les commandes CLI de provisioning.
• DB_ADMIN_PWD est vide au départ et doit être complété.
• DB_NAME dépend du projet généré.
• DB_APP_LOGIN peut reprendre le nom du projet, mais la valeur exacte à utiliser est celle présente dans env/dev.
• DB_APP_PWD est vide au départ et doit être complété.
• Les comptes MariaDB créés plus loin doivent correspondre exactement à ce fichier.

Ne copiez pas un nom de projet d'exemple sans vérifier votre propre env/dev.

---

Validation attendue

Les valeurs DB_NAME, DB_APP_LOGIN et DB_ADMIN_LOGIN sont identifiées dans votre propre env/dev.

3. Vérifier le dépôt Git local du projet

Objectif : Vérifier que le projet possède un dépôt Git local et un premier commit.

Attention

Ne recréez pas un commit initial si Forge l'a déjà créé.

forge new initialise en général le dépôt Git et crée un premier commit.
Vérifiez d'abord l'état :

git status
git log --oneline -5

Selon la version de Forge et le starter utilisé, le dépôt Git peut déjà être initialisé.
Vérifiez d'abord avec git status.

Si aucun dépôt n'est initialisé, ou si aucun commit n'a été créé, faites-le vous-même :

git init
git add .
git commit -m "Initialisation du projet Forge"

Ne refaites pas de commit initial si Forge en a déjà créé un.

---

Validation attendue

git status fonctionne et git log --oneline -5 montre au moins un commit.

4. Publier le projet sur GitHub

Objectif : Publier le dépôt Git local du projet sur GitHub sans quitter la procédure principale.

Attention

Le dépôt GitHub doit être vide au moment du premier push. Un README, un .gitignore ou une licence créés sur GitHub peuvent provoquer une divergence d'historique.

Cette étape associe le dépôt Git local du projet Forge à un dépôt GitHub distant.

Elle permet de sauvegarder le code du projet, de le partager entre plusieurs machines et de préparer un travail collaboratif.

À la fin de cette étape :

• le dépôt Git local est relié à GitHub ;
• la branche principale s'appelle main ;
• le premier push vers GitHub est effectué ;
• les prochains envois pourront se faire avec un simple git push.

4.1 Vérifier que le dépôt Git local est prêt

Cette étape suppose que le dépôt Git local a déjà été préparé à l'étape précédente.

Avant de publier le projet sur GitHub, vérifiez que vous êtes bien dans le dossier du projet Forge :

pwd
git status
git log --oneline -5

Le résultat attendu est :

• git status ne doit pas indiquer que le dossier est hors d'un dépôt Git ;
• le dépôt doit contenir au moins un commit ;
• le dossier de travail doit être propre, ou ne contenir que des modifications que vous souhaitez envoyer.

Si Git indique que le dossier n'est pas encore un dépôt, revenez à l'étape précédente pour initialiser le dépôt local avant de continuer.

Cette étape ne recrée pas le dépôt Git local. Elle vérifie simplement qu'il est prêt à être relié à GitHub.

4.2 Choisir le protocole GitHub

GitHub peut être utilisé avec deux protocoles.

Protocole	Forme de l'URL	Usage recommandé
SSH	git@github.com:UTILISATEUR/DEPOT.git	recommandé pour un poste de développement
HTTPS	https://github.com/UTILISATEUR/DEPOT.git	possible, mais nécessite un jeton d'accès personnel

Pour un poste de développement, le protocole SSH est recommandé.

La suite de cette procédure utilise donc SSH comme chemin principal.

Si vous choisissez HTTPS, utilisez l'URL HTTPS du dépôt à la place de l'URL SSH. GitHub ne s'authentifie pas avec le mot de passe du compte pour les opérations Git en HTTPS. Il faut utiliser un jeton d'accès personnel lorsque Git demande le mot de passe.

4.3 Vérifier l'authentification SSH GitHub

Avant de pousser le projet, GitHub doit reconnaître la machine depuis laquelle vous travaillez.

Vérifiez si une clé SSH existe déjà :

ls -la ~/.ssh/

Si vous voyez déjà les fichiers suivants, une clé existe probablement :

id_ed25519
id_ed25519.pub

Si ces fichiers n'existent pas, créez une clé SSH :

ssh-keygen -t ed25519 -C "votre.email@example.com"

Validez les questions avec Entrée pour accepter les valeurs par défaut.

Affichez ensuite la clé publique :

cat ~/.ssh/id_ed25519.pub

Copiez toute la ligne affichée.

Dans GitHub :

1. ouvrez Settings ;
2. allez dans SSH and GPG keys ;
3. cliquez sur New SSH key ;
4. collez la clé publique ;
5. validez avec Add SSH key.

Vérifiez ensuite que GitHub reconnaît la machine :

ssh -T git@github.com

La réponse attendue ressemble à ceci :

Hi VOTRE_PSEUDO! You've successfully authenticated.

Important : la clé SSH doit être celle de la machine qui lance git push.

Si vous travaillez depuis une VM, un serveur distant, WSL ou un conteneur, c'est la clé de cet environnement qui doit être ajoutée à GitHub.

4.4 Créer le dépôt GitHub vide

Sur GitHub, créez un nouveau dépôt.

Choisissez le nom du dépôt, par exemple :

mon-projet-forge

Pendant la création du dépôt, ne cochez pas :

• README ;
• .gitignore ;
• licence.

Le dépôt GitHub doit être vide.

Si GitHub crée un README ou une licence, il crée aussi un commit distant. Ce commit peut bloquer le premier push car l'historique distant et l'historique local ne sont pas les mêmes.

Après création du dépôt, copiez l'URL SSH :

git@github.com:UTILISATEUR/NOM_DU_DEPOT.git

4.5 Associer le dépôt local au dépôt GitHub

Vérifiez d'abord si un remote existe déjà :

git remote -v

Si aucun remote n'apparaît, ajoutez le dépôt GitHub :

git remote add origin git@github.com:UTILISATEUR/NOM_DU_DEPOT.git

Remplacez :

• UTILISATEUR par votre nom d'utilisateur GitHub ;
• NOM_DU_DEPOT par le nom réel du dépôt GitHub.

Si un remote origin existe déjà, ne le recréez pas.

Vérifiez plutôt son URL :

git remote -v

Si l'URL est incorrecte, remplacez-la :

git remote set-url origin git@github.com:UTILISATEUR/NOM_DU_DEPOT.git

4.6 Pousser le projet vers GitHub

Assurez-vous que la branche principale s'appelle main :

git branch -M main

Effectuez ensuite le premier push :

git push -u origin main

L'option -u lie la branche locale main à la branche distante main.

Elle est nécessaire au premier push.

Après cela, les prochains envois pourront se faire avec :

git push

4.7 Variante avec GitHub CLI

Cette variante est optionnelle.

Elle suppose que GitHub CLI est installé et déjà authentifié avec gh auth login.

Pour créer un dépôt privé et pousser le projet :

gh repo create NOM_DU_DEPOT --private --source=. --remote=origin --push

Pour créer un dépôt public :

gh repo create NOM_DU_DEPOT --public --source=. --remote=origin --push

Si vous utilisez cette variante, vous pouvez passer les étapes manuelles de création du dépôt GitHub et d'ajout du remote.

4.8 Résoudre les erreurs courantes du premier push

Cas particulier : vous avez choisi HTTPS au lieu de SSH

Si vous avez choisi HTTPS, l'URL du dépôt ressemble à ceci :

https://github.com/UTILISATEUR/NOM_DU_DEPOT.git

Dans ce cas, le remote doit être configuré avec l'URL HTTPS :

git remote set-url origin https://github.com/UTILISATEUR/NOM_DU_DEPOT.git

Au moment du push, Git peut demander :

Username:
Password:

Pour Username, indiquez votre nom d'utilisateur GitHub.

Pour Password, n'indiquez pas le mot de passe du compte GitHub. Utilisez un jeton d'accès personnel GitHub.

Si l'authentification échoue, vérifiez :

• que le jeton n'est pas expiré ;
• que le jeton a les droits nécessaires sur le dépôt ;
• que le remote utilise bien une URL HTTPS ;
• qu'un ancien identifiant GitHub n'est pas encore stocké dans le gestionnaire d'identifiants du système.

Pour un poste de développement régulier, SSH reste plus simple à maintenir.

Erreur : la branche n'a pas de branche distante liée

Message possible :

fatal: The current branch main has no upstream branch

Cause : vous avez lancé git push au lieu du premier push complet.

Correction :

git push -u origin main

Erreur : GitHub refuse la clé SSH

Message possible :

git@github.com: Permission denied (publickey)

Cause : GitHub ne reconnaît pas la clé SSH de cette machine.

Vérifiez d'abord l'authentification :

ssh -T git@github.com

Si le test échoue, reprenez l'étape 4.3.

Si le test réussit mais que le push échoue encore, chargez la clé dans l'agent SSH :

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
git push -u origin main

Erreur : le dépôt distant contient déjà un commit

Message possible :

! [rejected] main -> main
fetch first
non-fast-forward

Cause probable : un README, un .gitignore ou une licence a été ajouté sur GitHub lors de la création du dépôt.

Correction :

git pull origin main --allow-unrelated-histories --no-rebase
git push -u origin main

L'option --allow-unrelated-histories permet de fusionner deux historiques qui ont démarré séparément.

L'option --no-rebase choisit une fusion simple.

Si Git ouvre un éditeur pour le message de fusion :

• dans nano : Ctrl+O, puis Entrée, puis Ctrl+X ;
• dans vim : :wq, puis Entrée.

Pour éviter que Git redemande la stratégie de fusion plus tard :

git config --global pull.rebase false

Erreur : le remote origin existe déjà

Message possible :

error: remote origin already exists.

Cause : un remote origin est déjà configuré.

Vérifiez son URL :

git remote -v

Si elle est correcte, continuez directement avec le push :

git push -u origin main

Si elle est incorrecte, remplacez-la :

git remote set-url origin git@github.com:UTILISATEUR/NOM_DU_DEPOT.git
git push -u origin main

4.9 Vérifier que le projet est bien publié

Après le push, vérifiez l'état Git :

git status
git remote -v
git branch -vv

Vous devez voir que :

• le dépôt local est propre ;
• origin pointe vers GitHub ;
• la branche main suit origin/main.

Vous pouvez aussi ouvrir le dépôt GitHub dans le navigateur et vérifier que les fichiers du projet Forge sont présents.

Le projet est maintenant publié sur GitHub.

---

Validation attendue

Le dépôt local est relié à GitHub, origin pointe vers le bon dépôt et main suit origin/main.

5. Compléter env/dev

Objectif : Renseigner la configuration MariaDB du projet avant de créer la base et les comptes.

Attention

env/dev contient des secrets de développement. Il ne doit pas être publié tel quel si votre projet le considère comme local.

Cette étape appartient au projet.
Elle se refait pour chaque nouveau projet Forge, car chaque projet possède sa propre base et son propre compte applicatif.

Ouvrez le fichier env/dev :

nano env/dev

Complétez ou vérifiez les variables MariaDB suivantes :

DB_ADMIN_HOST=localhost
DB_ADMIN_PORT=3306
DB_ADMIN_LOGIN=forge_admin
DB_ADMIN_PWD=mot_de_passe_admin_local

DB_NAME=NOM_BASE
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci

DB_APP_HOST=localhost
DB_APP_PORT=3306
DB_APP_LOGIN=NOM_UTILISATEUR_APP
DB_APP_PWD=mot_de_passe_app_local
DB_POOL_SIZE=5

Remplacez :

• NOM_BASE par le nom réel de la base du projet ;
• NOM_UTILISATEUR_APP par le nom réel du compte applicatif ;
• mot_de_passe_admin_local par le mot de passe local du compte forge_admin ;
• mot_de_passe_app_local par le mot de passe local du compte applicatif.

Le nom de la base et le nom du compte applicatif peuvent reprendre le nom du projet, à condition de rester cohérents dans toute la procédure.

À partir de maintenant, les valeurs de env/dev sont la référence.
L'étape suivante crée la base et les comptes MariaDB à partir de ces valeurs.

---

Validation attendue

env/dev contient les valeurs définitives de DB_NAME, DB_ADMIN_LOGIN, DB_ADMIN_PWD, DB_APP_LOGIN et DB_APP_PWD.

6. Créer la base et les comptes MariaDB du projet

Objectif : Créer dans MariaDB la base et les comptes déclarés dans env/dev.

Attention

Les valeurs utilisées dans MariaDB doivent correspondre exactement aux valeurs renseignées dans env/dev.

Forge sépare trois niveaux d'accès :

root                -> administration locale du serveur, avec sudo
forge_admin         -> préparation de la base et application des migrations
DB_APP_LOGIN        -> accès applicatif au runtime, en lecture/écriture

forge db:init se connecte avec le compte indiqué dans DB_ADMIN_LOGIN.
Ce compte doit déjà exister : Forge ne le crée pas.
Le compte recommandé est forge_admin.

Relisez d'abord les valeurs du projet :

grep -E '^(DB_NAME|DB_ADMIN_LOGIN|DB_APP_LOGIN)=' env/dev

Ouvrez ensuite une console MariaDB administrateur :

sudo mariadb

Exécutez les commandes SQL suivantes en remplaçant les valeurs par celles de env/dev :

CREATE DATABASE IF NOT EXISTS `NOM_BASE`
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER IF NOT EXISTS 'forge_admin'@'localhost'
  IDENTIFIED BY 'mot_de_passe_admin_local';

CREATE USER IF NOT EXISTS 'NOM_UTILISATEUR_APP'@'localhost'
  IDENTIFIED BY 'mot_de_passe_app_local';

GRANT CREATE USER ON *.* TO 'forge_admin'@'localhost';

GRANT CREATE, ALTER, DROP, INDEX, REFERENCES,
      SELECT, INSERT, UPDATE, DELETE
ON `NOM_BASE`.* TO 'forge_admin'@'localhost'
WITH GRANT OPTION;

GRANT SELECT, INSERT, UPDATE, DELETE
ON `NOM_BASE`.* TO 'NOM_UTILISATEUR_APP'@'localhost';

FLUSH PRIVILEGES;

Quittez ensuite la console :

exit;

Précisions :

• NOM_BASE doit reprendre exactement la valeur de DB_NAME ;
• NOM_UTILISATEUR_APP doit reprendre exactement la valeur de DB_APP_LOGIN ;
• mot_de_passe_admin_local doit reprendre exactement la valeur de DB_ADMIN_PWD ;
• mot_de_passe_app_local doit reprendre exactement la valeur de DB_APP_PWD ;
• si DB_NAME contient un tiret, les backticks sont indispensables : `mon-projet` ;
• si DB_APP_LOGIN contient un tiret, gardez les quotes SQL : 'mon-projet'@'localhost'.

---

Validation attendue

La base, le compte forge_admin et le compte applicatif existent dans MariaDB, avec les mêmes valeurs que celles déclarées dans env/dev.

7. Vérifier le projet avec forge doctor

Objectif : Diagnostiquer le projet avec forge doctor avant l'initialisation de la base.

forge doctor

Cette commande diagnostique le projet et signale les points à corriger avant l'initialisation.

---

Validation attendue

forge doctor ne signale plus de blocage avant l'initialisation de la base.

8. Initialiser la base avec forge db:init

Objectif : Initialiser la base Forge et préparer la table technique des migrations.

Attention

Sur Debian, Ubuntu et dérivées, le compte root MariaDB utilise souvent unix_socket. Le compte recommandé pour Forge reste forge_admin.

forge db:init

Cette commande prépare la base du projet et crée la table technique forge_migrations, qui mémorise les migrations déjà appliquées.

Si la commande s'arrête sur :

[ERREUR] Connexion MariaDB admin impossible. Vérifiez DB_ADMIN_* dans env/dev.

Forge n'a pas pu se connecter avec le compte indiqué dans DB_ADMIN_LOGIN.
À vérifier :

• le compte existe dans MariaDB ;
• le mot de passe correspond à DB_ADMIN_PWD ;
• DB_ADMIN_HOST est correct, généralement localhost ;
• DB_ADMIN_PORT est correct, généralement 3306 ;
• le compte a été créé avec le même hôte que celui utilisé par Forge ;
• DB_ADMIN_PWD n'est pas resté vide dans env/dev.

Sur Debian, Ubuntu et leurs dérivées, le compte root MariaDB utilise souvent l'authentification unix_socket, ce qui peut échouer en connexion TCP.
Le parcours recommandé reste donc de créer un compte forge_admin.

---

Validation attendue

forge db:init se termine sans erreur et la table technique des migrations est prête.

9. Lancer le serveur de développement

Objectif : démarrer le serveur Forge en mode développement et ouvrir le projet dans le navigateur.

Avant de lancer le serveur, vérifiez le port configuré dans env/dev.

grep -E "^APP_PORT=" env/dev

Exemple attendu :

APP_PORT=8000

Le serveur de développement utilisera ce port au démarrage.

Si le port est déjà utilisé par une autre application, modifiez la valeur dans env/dev, par exemple :

APP_PORT=8001

Lancez ensuite le serveur :

forge run

Ouvrez le projet dans le navigateur en utilisant le port configuré
(HTTPS de développement, certificat auto-signé généré par forge new) :

https://127.0.0.1:8000

Si vous avez modifié APP_PORT, adaptez l'adresse.

Exemple :

http://127.0.0.1:8001

Validation attendue

La page d'accueil du projet Forge doit s'afficher dans le navigateur.

Le port utilisé dans l'URL doit correspondre à la valeur configurée dans env/dev.

En cas d'erreur : le port est déjà utilisé

Si le terminal indique que le port est déjà utilisé, choisissez un autre port dans env/dev.

Exemple :

APP_PORT=8001

Relancez ensuite le serveur :

forge run

Ouvrez enfin l'adresse correspondante dans le navigateur :

http://127.0.0.1:8001

Validation finale

Le projet Forge est correctement installé si :

• le serveur démarre avec forge run ;
• le port utilisé correspond à la valeur APP_PORT configurée dans env/dev ;
• la page d'accueil du projet s'affiche dans le navigateur ;
• aucune erreur bloquante n'apparaît dans le terminal.

Le projet est maintenant prêt pour le développement.

Poursuivre

Votre projet Forge est maintenant installé, configuré et lancé.

La suite logique est de suivre le parcours du starter Welcome Forge.
Il sert à prendre en main un projet Forge réel, étape par étape, sans partir directement dans les sujets avancés.

Vous y verrez notamment :

• l'organisation d'un projet Forge ;
• le rôle des routes ;
• le rôle des contrôleurs ;
• le rôle des vues ;
• l'utilisation de forge run ;
• les premières modifications à réaliser dans le projet.

Commencer le parcours : Welcome Forge

Approfondir

Après le parcours Welcome Forge, vous pourrez revenir vers les pages techniques selon vos besoins :

• Préparer MariaDB : installation détaillée et dépannage.
• Comptes MariaDB d'un projet : comptes, droits et vérifications.
• Migrations SQL : cycle des migrations Forge.
• Installer les opt-ins Forge : extensions officielles du framework.
• Préparer un déploiement en production : serveur, WSGI et reverse proxy.
• Installer Forge depuis les sources GitHub : contribuer ou travailler depuis le dépôt source.