211 lines
No EOL
5.6 KiB
Markdown
211 lines
No EOL
5.6 KiB
Markdown
# 🏙️ CityGame — Fullstack Template
|
||
|
||
> **NX Monorepo** · Spring Boot 3 · React 18 · TypeScript · Vite · Docker Compose
|
||
|
||
---
|
||
|
||
## Stack
|
||
|
||
| Layer | Technology |
|
||
|---|---|
|
||
| **Backend** | Spring Boot 3.4, Java 21, Maven, Lombok, JPA, Actuator |
|
||
| **Frontend** | React 18, TypeScript, Vite 5, Vitest |
|
||
| **Database** | H2 (dev) / PostgreSQL 16 (prod) |
|
||
| **Infra** | Docker Compose, nginx, multi-stage builds |
|
||
| **Monorepo** | NX 21 — caching, task graph, affected builds |
|
||
|
||
---
|
||
|
||
## Quickstart
|
||
|
||
### Prérequis
|
||
|
||
- Node.js ≥ 20
|
||
- pnpm ≥ 10 (`npm install -g pnpm` ou `corepack enable`)
|
||
- Java 21
|
||
- Docker + Docker Compose
|
||
|
||
### Installation
|
||
|
||
```bash
|
||
git clone <repo-url> citygame
|
||
cd citygame
|
||
pnpm install
|
||
```
|
||
|
||
---
|
||
|
||
## Commandes
|
||
|
||
### 🔥 Mode Développement (hot reload)
|
||
|
||
```bash
|
||
# Lance frontend (Vite HMR :5173) + backend (Spring DevTools :8080) en parallèle
|
||
pnpm dev
|
||
|
||
# Ou individuellement :
|
||
pnpm dev:frontend # Vite dev server → http://localhost:5173
|
||
pnpm dev:backend # Spring Boot → http://localhost:8080
|
||
```
|
||
|
||
> Le backend utilise H2 en mémoire en mode dev. Pas besoin de Docker.
|
||
> Pour utiliser PostgreSQL en dev : `docker compose -f docker-compose.dev.yml up -d`
|
||
|
||
### 🏗️ Build
|
||
|
||
```bash
|
||
# Build tout (frontend Vite + backend Maven JAR)
|
||
pnpm build
|
||
|
||
# Build individuellement :
|
||
pnpm build:frontend # → dist/apps/frontend/
|
||
pnpm build:backend # → apps/backend/target/*.jar
|
||
|
||
# Build les images Docker
|
||
pnpm docker:build
|
||
pnpm docker:build:frontend
|
||
pnpm docker:build:backend
|
||
```
|
||
|
||
### 🚀 Production (Docker Compose)
|
||
|
||
```bash
|
||
# Copier et configurer les variables d'environnement
|
||
cp .env.example .env
|
||
|
||
# Démarrer la stack prod (après docker:build)
|
||
pnpm start # docker compose up (foreground)
|
||
pnpm start:detach # docker compose up -d (background)
|
||
pnpm stop # docker compose down
|
||
pnpm logs # docker compose logs -f
|
||
```
|
||
|
||
### 🧪 Tests
|
||
|
||
```bash
|
||
pnpm test # Tous les tests
|
||
pnpm test:frontend # Vitest
|
||
pnpm test:backend # Maven Surefire (JUnit 5)
|
||
```
|
||
|
||
### 📊 NX Tools
|
||
|
||
```bash
|
||
npx nx graph # Visualise le graphe de dépendances
|
||
npx nx affected -t test # Tests des projets affectés par les changements
|
||
npx nx affected -t build # Build uniquement ce qui a changé
|
||
npx nx reset # Nettoie le cache NX
|
||
```
|
||
|
||
---
|
||
|
||
## Structure
|
||
|
||
```
|
||
CityGame/
|
||
├── apps/
|
||
│ ├── backend/ # Spring Boot (Maven)
|
||
│ │ ├── src/main/java/com/citygame/
|
||
│ │ │ ├── CityGameApplication.java
|
||
│ │ │ ├── api/HealthController.java
|
||
│ │ │ └── config/CorsConfig.java
|
||
│ │ ├── src/main/resources/
|
||
│ │ │ ├── application.yml # Base config
|
||
│ │ │ ├── application-dev.yml # H2 + DevTools
|
||
│ │ │ └── application-prod.yml # PostgreSQL
|
||
│ │ ├── pom.xml
|
||
│ │ ├── project.json # NX targets
|
||
│ │ └── Dockerfile # Multi-stage
|
||
│ │
|
||
│ └── frontend/ # Vite + React + TypeScript
|
||
│ ├── src/
|
||
│ │ ├── api/health.ts # Client API typé
|
||
│ │ ├── App.tsx
|
||
│ │ └── main.tsx
|
||
│ ├── vite.config.ts # Proxy /api → backend
|
||
│ ├── project.json # NX targets
|
||
│ └── Dockerfile # Multi-stage (nginx)
|
||
│
|
||
├── docker-compose.yml # Prod stack
|
||
├── docker-compose.dev.yml # Dev (DB seulement)
|
||
├── nx.json # Config NX + caching
|
||
├── package.json # Scripts & workspace
|
||
└── .env.example # Variables template
|
||
```
|
||
|
||
---
|
||
|
||
## API Endpoints
|
||
|
||
| Méthode | URL | Description |
|
||
|---|---|---|
|
||
| `GET` | `/api/hello` | Demo endpoint (message + timestamp) |
|
||
| `GET` | `/actuator/health` | Health check Spring Boot |
|
||
| `GET` | `/actuator/info` | Infos application |
|
||
| `GET` | `/h2-console` | Console H2 (dev seulement) |
|
||
|
||
---
|
||
|
||
## Ajouter une fonctionnalité
|
||
|
||
### Nouveau endpoint backend
|
||
|
||
1. Créer un controller dans `apps/backend/src/main/java/com/citygame/api/`
|
||
2. Redémarrage automatique via Spring DevTools
|
||
|
||
### Nouveau composant frontend
|
||
|
||
1. Créer dans `apps/backend/src/`
|
||
2. HMR Vite — mise à jour sans rechargement
|
||
|
||
### Nouvelle app dans le monorepo
|
||
|
||
```bash
|
||
# Nouvelle app React
|
||
npx nx g @nx/react:app apps/my-new-app --bundler=vite
|
||
|
||
# Nouvelle lib partagée TypeScript
|
||
npx nx g @nx/js:lib libs/shared-types
|
||
```
|
||
|
||
---
|
||
|
||
## Configuration Docker (prod)
|
||
|
||
Copier `.env.example` → `.env` et configurer :
|
||
|
||
```env
|
||
DB_PASSWORD=un_mot_de_passe_fort
|
||
CORS_ALLOWED_ORIGINS=https://votredomaine.com
|
||
```
|
||
|
||
---
|
||
|
||
## CI/CD (OneDev)
|
||
|
||
Le fichier [`.onedev-buildspec.yml`](.onedev-buildspec.yml) définit trois jobs :
|
||
|
||
| Job | Rôle |
|
||
|-----|------|
|
||
| **Build and Test** | `pnpm install`, build NX, tests, rapports JUnit |
|
||
| **Docker Build** | Vérifie les Dockerfiles (export OCI local) |
|
||
| **Docker Publish** | Push registry sur `main` / `master` uniquement |
|
||
|
||
**Déclenchement :** push direct sur `main`, `master`, `develop` ; branches type `feature/*` ou `ci/*` uniquement via pull request (pas de doublon).
|
||
|
||
**Image CI recommandée** (évite `apt-get` à chaque run) :
|
||
|
||
```bash
|
||
docker build -f ci/Dockerfile -t <registry>/citygame-ci:latest .
|
||
docker push <registry>/citygame-ci:latest
|
||
```
|
||
|
||
Dans OneDev : **Project → Settings → Build → Job Properties** → `ciBuildImage` = `<registry>/citygame-ci:latest`.
|
||
|
||
Configurer la connexion registry sur l’exécuteur Docker pour le job **Docker Publish** ([doc](https://docs.onedev.io/tutorials/cicd/build-docker-image)).
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT |