02 - Création du dépôt Forge-web¶

1. Objectif du tutoriel¶

Ce tutoriel décrit la procédure propre pour créer le projet local Forge-web, séparé du framework Forge.

Le projet Forge-web servira à publier le site officiel :

https://forgemvc.com

Il contiendra progressivement :

la landing page publique ;
la documentation publique de Forge ;
les sources MkDocs ;
les notes d’infrastructure ;
les scripts de génération ou de déploiement ;
plus tard, les éléments nécessaires à la publication sur le serveur.

Ce projet ne doit pas modifier le cœur du framework Forge.

2. Principe général¶

Le framework Forge et le site Forge-web doivent rester séparés.

La séparation évite de mélanger :

le développement du framework Python ;
la documentation publique ;
la landing page ;
l’infrastructure de publication ;
les notes DNS / HTTPS / Proxmox.

La bonne organisation est donc :

/home/roger/Projets/
├── Forge/        # Framework Forge
└── Forge-web/    # Site officiel forgemvc.com

Cette séparation est importante. Le site web n’est pas une application métier Forge et ne doit pas devenir une extension du framework.

3. Résultat final attendu¶

À la fin de la procédure, on doit obtenir :

Forge-web/
├── .git/
├── .gitignore
├── README.md
├── docs/
│   └── .gitkeep
├── infra/
│   └── .gitkeep
├── landing/
│   └── assets/
│       ├── css/
│       │   └── .gitkeep
│       ├── img/
│       │   └── .gitkeep
│       └── js/
│           └── .gitkeep
├── notes/
│   └── .gitkeep
└── scripts/
    └── .gitkeep

Le dépôt local doit être synchronisé avec GitHub :

https://github.com/caucrogeGit/Forge-web.git

La branche principale doit être :

main

4. Prérequis¶

Avant de commencer, il faut disposer de :

Git installé ;
Python installé ;
un compte GitHub ;
un dossier de travail local, ici /home/roger/Projets.

Vérification :

cd /home/roger/Projets
pwd
ls -la
git --version
python3 --version

Résultat attendu dans notre cas :

/home/roger/Projets
git version 2.43.0
Python 3.12.3

Il faut aussi vérifier que le dossier Forge-web n’existe pas déjà :

test -e Forge-web && echo "ERREUR: Forge-web existe déjà" || echo "OK: Forge-web absent"

Résultat attendu :

OK: Forge-web absent

5. Création de la structure du projet¶

On crée uniquement les dossiers nécessaires au démarrage.

cd /home/roger/Projets

mkdir -p Forge-web/{landing/assets/{css,js,img},docs,infra,notes,scripts}

find Forge-web -maxdepth 4 -type d | sort

Résultat attendu :

Forge-web
Forge-web/docs
Forge-web/infra
Forge-web/landing
Forge-web/landing/assets
Forge-web/landing/assets/css
Forge-web/landing/assets/img
Forge-web/landing/assets/js
Forge-web/notes
Forge-web/scripts

Explication des dossiers¶

Dossier	Rôle
`landing/`	Contiendra la future page d’accueil statique de forgemvc.com
`landing/assets/css/`	Feuilles CSS de la landing page
`landing/assets/js/`	JavaScript éventuel de la landing page
`landing/assets/img/`	Logos, images et illustrations
`docs/`	Sources de documentation ou contenu public MkDocs
`infra/`	Notes ou fichiers d’infrastructure sans secrets
`notes/`	Notes de travail du projet Forge-web
`scripts/`	Scripts locaux de génération ou de déploiement

Le dossier site/ n’est pas créé manuellement ici. Il sera généré plus tard par MkDocs et ignoré par Git.

6. Création du README¶

Le fichier README.md sert à expliquer clairement le rôle du dépôt.

Créer le fichier :

cd /home/roger/Projets/Forge-web
nano README.md

Contenu recommandé :

# Forge-web

Site officiel du framework Forge.

Objectif du projet :

- publier https://forgemvc.com ;
- héberger la landing page publique ;
- héberger la documentation Forge générée avec MkDocs ;
- préparer un déploiement statique simple ;
- garder ce projet séparé du framework Forge.

## Périmètre

Ce dépôt concerne uniquement Forge-web :

- landing page ;
- documentation publique ;
- génération statique ;
- notes d'infrastructure ;
- scripts de build et de déploiement.

Ce dépôt ne doit pas modifier le cœur du framework Forge.

## Structure initiale

- landing/ : source de la landing page statique ;
- docs/ : documentation publique ou sources MkDocs ;
- site/ : site généré, non versionné ;
- infra/ : notes et fichiers d'infrastructure sans secrets ;
- notes/ : notes de travail du projet ;
- scripts/ : scripts locaux de génération ou déploiement.

## Décision initiale

Le site sera statique dans un premier temps.

MkDocs servira à générer la documentation.

Le reverse proxy et HTTPS seront traités plus tard, probablement avec Caddy.

Proxmox ne doit jamais être exposé directement au public.

Pourquoi ce README est important¶

Le README fixe dès le départ le périmètre du dépôt.

Il évite les dérives suivantes :

transformer Forge-web en application Forge ;
modifier le cœur du framework depuis ce dépôt ;
mélanger site web, framework, mail, firewall et Proxmox ;
placer des secrets dans le projet.

7. Création du `.gitignore`¶

Le fichier .gitignore indique à Git ce qu’il ne doit pas versionner.

Créer le fichier :

cd /home/roger/Projets/Forge-web
nano .gitignore

Contenu recommandé :

# Python
__pycache__/
*.py[cod]
.venv/
venv/

# MkDocs / build statique
site/

# Environnements et secrets
.env
.env.*
*.key
*.pem
*.crt
secrets/
.envrc

# Système / éditeurs
.DS_Store
Thumbs.db
.vscode/
.idea/

# Logs
*.log
logs/

Pourquoi ignorer `site/`¶

Le dossier site/ sera généré automatiquement par MkDocs.

Il ne doit pas être versionné dans ce dépôt de sources, car il s’agit d’un artefact de build.

On versionne les sources, pas le résultat généré.

Pourquoi ignorer les secrets¶

Le dépôt ne doit jamais contenir :

mots de passe ;
clés privées ;
certificats privés ;
tokens GitHub ;
tokens Cloudflare ;
fichiers .env réels.

C’est indispensable, surtout pour un projet destiné à être publié.

8. Ajout des fichiers `.gitkeep`¶

Git ne versionne pas les dossiers vides.

Pour conserver la structure initiale, on ajoute un fichier .gitkeep dans chaque dossier vide.

cd /home/roger/Projets/Forge-web

find . -type d -empty -exec touch {}/.gitkeep \;

find . -maxdepth 4 -type f | sort

Résultat attendu :

./.gitignore
./README.md
./docs/.gitkeep
./infra/.gitkeep
./landing/assets/css/.gitkeep
./landing/assets/img/.gitkeep
./landing/assets/js/.gitkeep
./notes/.gitkeep
./scripts/.gitkeep

Attention : il ne faut pas garder de .gitkeep à la racine du projet. La racine contient déjà des fichiers, donc elle n’est pas vide.

Si un .gitkeep racine a été créé par erreur :

rm -f ./.gitkeep

9. Initialisation du dépôt Git local¶

Depuis la racine du projet :

cd /home/roger/Projets/Forge-web

git init

Puis vérifier l’état :

git status --short

Résultat attendu :

?? .gitignore
?? README.md
?? docs/
?? infra/
?? landing/
?? notes/
?? scripts/

Les fichiers sont présents mais pas encore suivis par Git.

10. Ajout des fichiers à l’index Git¶

Ajouter les fichiers initiaux :

cd /home/roger/Projets/Forge-web

git add .gitignore README.md docs infra landing notes scripts

Vérifier :

git status --short

Résultat attendu :

A  .gitignore
A  README.md
A  docs/.gitkeep
A  infra/.gitkeep
A  landing/assets/css/.gitkeep
A  landing/assets/img/.gitkeep
A  landing/assets/js/.gitkeep
A  notes/.gitkeep
A  scripts/.gitkeep

La lettre A signifie que Git va ajouter ces fichiers au prochain commit.

11. Premier commit local¶

Créer le premier commit :

cd /home/roger/Projets/Forge-web

git commit -m "init: create Forge-web project structure"

Vérifier :

git status --short
git log --oneline -1
git branch --show-current

Résultat attendu :

a9e962e init: create Forge-web project structure
main

Le statut Git doit être propre, c’est-à-dire sans fichier modifié ou non suivi.

12. Création du dépôt GitHub¶

Créer un dépôt GitHub séparé nommé :

Forge-web

Paramètres recommandés :

Visibility : Private au départ
README     : non
.gitignore : non
License    : non

Il ne faut pas demander à GitHub de créer un README ou un .gitignore, car ces fichiers existent déjà localement.

Sinon GitHub créerait un historique différent, ce qui compliquerait le premier push.

Dépôt créé dans notre cas :

https://github.com/caucrogeGit/Forge-web.git

13. Ajout du dépôt distant¶

Ajouter GitHub comme remote origin :

cd /home/roger/Projets/Forge-web

git remote add origin https://github.com/caucrogeGit/Forge-web.git

Vérifier :

git remote -v

Résultat attendu :

origin  https://github.com/caucrogeGit/Forge-web.git (fetch)
origin  https://github.com/caucrogeGit/Forge-web.git (push)

14. Premier push vers GitHub¶

Envoyer la branche locale main vers GitHub :

cd /home/roger/Projets/Forge-web

git push -u origin main

Résultat attendu :

[new branch]      main -> main
la branche 'main' est paramétrée pour suivre 'origin/main'.

L’option -u permet d’associer la branche locale main à la branche distante origin/main.

Après cela, les futurs pushs pourront se faire simplement avec :

git push

15. Vérification finale¶

Vérifier que tout est propre :

cd /home/roger/Projets/Forge-web

git status
git branch -vv
git log --oneline -1
git remote -v

Résultat attendu :

Sur la branche main
Votre branche est à jour avec 'origin/main'.

rien à valider, la copie de travail est propre

La branche doit indiquer :

main [origin/main]

Le dernier commit doit être :

a9e962e init: create Forge-web project structure

Le remote doit être :

origin  https://github.com/caucrogeGit/Forge-web.git (fetch)
origin  https://github.com/caucrogeGit/Forge-web.git (push)

16. État final obtenu¶

À la fin de cette procédure, le projet est correctement initialisé.

État obtenu :

Forge-web local créé
Git local initialisé
Premier commit fait
Dépôt GitHub séparé créé
Remote origin ajouté
Premier push effectué
Branche main synchronisée avec origin/main

Le dépôt local est propre :

rien à valider, la copie de travail est propre

17. Points de vigilance¶

17.1 Ne pas travailler dans le dépôt Forge¶

Avant toute commande, vérifier le dossier courant :

pwd

Le bon dossier est :

/home/roger/Projets/Forge-web

Pas :

/home/roger/Projets/Forge

17.2 Ne pas versionner le dossier `site/`¶

site/ sera généré automatiquement.

Il doit rester dans .gitignore.

17.3 Ne pas stocker de secrets¶

Aucun secret ne doit être ajouté au dépôt.

Exemples interdits :

.env
clé SSH privée
clé Cloudflare
clé GitHub
clé TLS privée
mot de passe serveur

17.4 HTTPS ou SSH pour GitHub¶

Le remote actuel utilise HTTPS :

https://github.com/caucrogeGit/Forge-web.git

Ce n’est pas bloquant.

Si GitHub demande trop souvent une authentification, il sera possible plus tard de basculer en SSH :

git@github.com:caucrogeGit/Forge-web.git

18. Conclusion¶

Le dépôt Forge-web est prêt.

Il est maintenant possible de passer à la suite du projet :

03 — Landing page

La prochaine étape consistera à créer la première page publique statique de forgemvc.com, sans toucher au framework Forge.

02 - Création du dépôt Forge-web¶

1. Objectif du tutoriel¶

2. Principe général¶

3. Résultat final attendu¶

4. Prérequis¶

5. Création de la structure du projet¶

Explication des dossiers¶

6. Création du README¶

Pourquoi ce README est important¶

7. Création du .gitignore¶

Pourquoi ignorer site/¶

Pourquoi ignorer les secrets¶

8. Ajout des fichiers .gitkeep¶

9. Initialisation du dépôt Git local¶

10. Ajout des fichiers à l’index Git¶

11. Premier commit local¶

12. Création du dépôt GitHub¶

13. Ajout du dépôt distant¶

14. Premier push vers GitHub¶

15. Vérification finale¶

16. État final obtenu¶

17. Points de vigilance¶

17.1 Ne pas travailler dans le dépôt Forge¶

17.2 Ne pas versionner le dossier site/¶

17.3 Ne pas stocker de secrets¶

17.4 HTTPS ou SSH pour GitHub¶

18. Conclusion¶

7. Création du `.gitignore`¶

Pourquoi ignorer `site/`¶

8. Ajout des fichiers `.gitkeep`¶

17.2 Ne pas versionner le dossier `site/`¶