167 lines
8.1 KiB
Markdown
167 lines
8.1 KiB
Markdown
# ChessCubing Arena
|
|
|
|
Application web mobile-first pour telephone et tablette, maintenant migree vers **Blazor WebAssembly en C# / .NET 10**.
|
|
|
|
## Ce que fait l'application
|
|
|
|
- configure une rencontre `Twice` ou `Time`
|
|
- separe l'experience en pages dediees : configuration, phase chrono, phase cube
|
|
- permet de definir librement le temps de partie et le temps par coup
|
|
- suit les quotas `FAST`, `FREEZE` et `MASTERS`
|
|
- orchestre la phase cube avec designation du cube, capture des temps et preparation de la partie suivante
|
|
- applique la logique du double coup V2 en `Twice`
|
|
- applique les ajustements `bloc -` et `bloc +` en `Time` avec plafond de 120 s pris en compte
|
|
- conserve l'etat du match dans le navigateur
|
|
- propose une page chrono pensee pour le telephone avec deux grandes zones tactiles
|
|
- ouvre automatiquement la page cube des que la phase chess est terminee
|
|
|
|
## Architecture
|
|
|
|
Le coeur de l'application se trouve dans `ChessCubing.App/`.
|
|
|
|
- `ChessCubing.App/Pages/` : pages Razor du site et de l'application
|
|
- `ChessCubing.App/Services/MatchEngine.cs` : logique metier des matchs
|
|
- `ChessCubing.App/Services/MatchStore.cs` : persistance navigateur
|
|
- `ChessCubing.App/Services/AppAuthenticationStateProvider.cs` : session locale cote client
|
|
- `ChessCubing.Server/` : backend d'authentification Keycloak et API utilisateur reliee a MySQL
|
|
- `ChessCubing.App/wwwroot/` : assets statiques, manifeste, PDFs, appli Ethan
|
|
- `keycloak/realm/chesscubing-realm.json` : realm importable avec client Keycloak et roles
|
|
- `keycloak/scripts/init-config.sh` : synchronisation automatique du client Keycloak au demarrage
|
|
- `docker-compose.yml` + `Dockerfile` + `Dockerfile.auth` : front Blazor, API d'auth, Keycloak/Postgres et MySQL pour les donnees du site
|
|
|
|
Le projet continue a exposer les routes historiques `index.html`, `application.html`, `chrono.html`, `cube.html` et `reglement.html`.
|
|
|
|
## Authentification Keycloak
|
|
|
|
L'application embarque maintenant une authentification integree basee sur Keycloak, sans redirection utilisateur vers une page externe.
|
|
|
|
- toutes les pages du site restent accessibles sans connexion
|
|
- un menu general en haut des pages site regroupe la navigation et les actions `Se connecter` / `Creer un compte` dans une modal integree
|
|
- le formulaire de connexion et le formulaire de creation de compte sont rendus directement dans l'application
|
|
- un backend local `ChessCubing.Server` appelle Keycloak cote serveur pour la connexion, l'inscription et la recuperation du profil
|
|
- une session cookie locale est ensuite exposee au front via `/api/auth/session`
|
|
- les roles Keycloak du realm restent exposes dans l'application
|
|
- l'etat du match est isole par utilisateur dans le navigateur grace a une cle de stockage derivee du compte connecte
|
|
- une page `utilisateur` permet maintenant d'editer un profil du site persiste en base MySQL via `/api/users/me`
|
|
- une page `administration` reservee au role `admin` permet maintenant de parcourir et modifier les utilisateurs du site via `/api/admin/users`
|
|
|
|
Le realm importe par defaut :
|
|
|
|
- realm : `chesscubing`
|
|
- client Keycloak : `chesscubing-web`
|
|
- roles de realm : `admin`, `organizer`, `player`
|
|
- inscription utilisateur : activee
|
|
- direct access grant : active
|
|
|
|
La gestion des utilisateurs peut maintenant demarrer depuis la page d'administration du site pour les usages courants. La console d'administration Keycloak reste utile pour les reglages avances, notamment les roles.
|
|
|
|
## Demarrage local
|
|
|
|
### Avec Docker
|
|
|
|
```bash
|
|
docker compose down
|
|
docker compose up -d --build
|
|
```
|
|
|
|
L'application est ensuite disponible sur `http://localhost:8080`.
|
|
|
|
La console Keycloak est servie via le meme nginx sur `http://localhost:8080/auth/admin/`.
|
|
L'API d'authentification integree est servie derriere le meme point d'entree via `/api/auth/*`.
|
|
L'API utilisateur et sa persistance MySQL sont egalement servies via `/api/users/*`.
|
|
|
|
Identifiants d'administration par defaut pour le premier demarrage local :
|
|
|
|
- utilisateur : `admin`
|
|
- mot de passe : `admin`
|
|
|
|
Ces valeurs peuvent etre surchargees via les variables d'environnement de `.env.example`.
|
|
La base MySQL du site utilise les variables `SITE_DB_*` du meme fichier.
|
|
Pour un deploiement hors localhost, `PUBLIC_BASE_URL` doit pointer vers l'URL publique du site et `WEB_PORT` vers le port HTTP expose.
|
|
|
|
Au demarrage, le service `keycloak-init` resynchronise automatiquement le realm courant pour garder l'inscription active et autoriser le flux de connexion integre, meme si la base Keycloak existe deja.
|
|
|
|
Si vous voulez reimporter completement le realm fourni dans `keycloak/realm/`, il faut repartir d'une base vide, par exemple avec `docker compose down -v` avant le redemarrage.
|
|
|
|
### Avec .NET 10
|
|
|
|
```bash
|
|
dotnet restore ChessCubing.App/ChessCubing.App.csproj
|
|
dotnet run --project ChessCubing.App/ChessCubing.App.csproj
|
|
```
|
|
|
|
Le mode Docker reste la voie recommandee pour cette integration, car nginx y reverse-proxy egalement Keycloak sous `/auth/` et l'API d'auth sous `/api/`.
|
|
|
|
## Deploiement dans un LXC Proxmox
|
|
|
|
Deux scripts Bash permettent de creer un conteneur LXC Debian sur Proxmox puis de le mettre a jour depuis Git.
|
|
|
|
Prerrequis sur la machine qui lance les scripts :
|
|
|
|
- en mode distant : `ssh` et `sshpass`
|
|
- en mode local sur l'hote Proxmox : aucun paquet supplementaire n'est installe sur Proxmox
|
|
|
|
Le deploiement dans le LXC Proxmox utilise maintenant Docker dans le conteneur pour lancer la meme stack qu'en local : `web`, `auth`, `keycloak`, `postgres` et `mysql`.
|
|
|
|
Le script prepare une URL publique pour Keycloak via `PUBLIC_BASE_URL`, installe Docker dans le LXC, puis lance la stack dans le conteneur.
|
|
|
|
Les mises a jour conservent maintenant `mysql`, `postgres` et `keycloak` en place. Le script ne fait plus de `docker compose down` ni de purge complete des images a chaque update, ce qui evite de retelecharger ou recreer inutilement l'infrastructure.
|
|
|
|
Si le site est expose derriere un reverse proxy, `PUBLIC_BASE_URL` doit etre l'URL publique finale servie par ce proxy.
|
|
|
|
Pour un usage confortable, il est recommande de prevoir un LXC avec au moins 2 vCPU, 4 Go de RAM et 16 Go de disque.
|
|
|
|
### Installer un nouveau LXC
|
|
|
|
```bash
|
|
./scripts/install-proxmox-lxc.sh \
|
|
--proxmox-host 10.0.0.2 \
|
|
--proxmox-user root@pam \
|
|
--proxmox-password 'secret' \
|
|
--public-base-url https://jeu.exemple.fr
|
|
```
|
|
|
|
Version "curl | bash" :
|
|
|
|
```bash
|
|
bash -c "$(curl -fsSL https://git.jeannerot.fr/christophe/chesscubing/raw/branch/main/install-chesscubing-proxmox.sh)"
|
|
```
|
|
|
|
### Mettre a jour depuis Git
|
|
|
|
```bash
|
|
./scripts/update-proxmox-lxc.sh \
|
|
--proxmox-host 10.0.0.2 \
|
|
--proxmox-user root@pam \
|
|
--proxmox-password 'secret' \
|
|
--ctid 120 \
|
|
--public-base-url https://jeu.exemple.fr \
|
|
--disk-gb 16
|
|
```
|
|
|
|
Version "curl | bash" :
|
|
|
|
```bash
|
|
bash -c "$(curl -fsSL https://git.jeannerot.fr/christophe/chesscubing/raw/branch/main/update-chesscubing-proxmox.sh)"
|
|
```
|
|
|
|
## Fichiers cles
|
|
|
|
- `ChessCubing.App/Pages/Home.razor` : page d'accueil du site
|
|
- `ChessCubing.App/Pages/UserPage.razor` : page utilisateur connectee a MySQL
|
|
- `ChessCubing.App/Pages/AdminPage.razor` : premiere page d'administration pour gerer les utilisateurs
|
|
- `ChessCubing.App/Pages/ApplicationPage.razor` : configuration et reprise de match
|
|
- `ChessCubing.App/Pages/ChronoPage.razor` : phase chrono
|
|
- `ChessCubing.App/Pages/CubePage.razor` : phase cube
|
|
- `ChessCubing.App/Pages/RulesPage.razor` : synthese du reglement
|
|
- `ChessCubing.App/Services/MatchEngine.cs` : regles de jeu et transitions
|
|
- `ChessCubing.App/Services/AppAuthenticationStateProvider.cs` : etat de session cote client
|
|
- `ChessCubing.Server/Program.cs` : endpoints `/api/auth/*` et `/api/users/*`
|
|
- `ChessCubing.Server/Program.cs` : endpoints `/api/auth/*`, `/api/users/*` et `/api/admin/users/*`
|
|
- `ChessCubing.Server/Users/MySqlUserProfileStore.cs` : creation de table et persistance du profil utilisateur
|
|
- `keycloak/realm/chesscubing-realm.json` : realm, roles et client Keycloak importes
|
|
- `keycloak/scripts/init-config.sh` : mise en conformite du client Keycloak au demarrage
|
|
- `docker-compose.yml` + `Dockerfile` + `Dockerfile.auth` : execution locale
|
|
- `scripts/install-proxmox-lxc.sh` : creation et deploiement d'un LXC Proxmox
|
|
- `scripts/update-proxmox-lxc.sh` : mise a jour d'un LXC existant depuis Git
|