Installation locale

Installation locale

Guide pas à pas pour faire tourner Swor sur ta machine, même si tu débutes avec Node ou PHP.

Le projet est composé de deux applications qui tournent en parallèle :

Appli	Techno	URL locale	Rôle
Front	Next.js (React)	http://localhost:3000	Le site dans le navigateur
API	Laravel (PHP)	http://localhost:8000	Auth, forum, persos, factions…
BDD	PostgreSQL (Docker)	port 54322	Stockage des données

Le front appelle l'API en JSON. L'API lit et écrit dans Postgres.

---

Étape 0 — Outils à installer

Installe dans cet ordre. Compte 20 à 30 minutes la première fois.

1. Git

• Téléchargement : https://git-scm.com/downloads
• Vérification dans un terminal :

git --version

2. Node.js 20+

• Téléchargement (version LTS) : https://nodejs.org/
• Le projet exige Node ≥ 20 (fichier .nvmrc à la racine du repo).
• Vérification :

node --version
npm --version

Option utile plus tard : nvm (Mac/Linux) ou nvm-windows.

3. PHP 8.2+ et Composer

Mac (Homebrew) — installe Homebrew si besoin :

brew install php composer

Windows — option simple : Laragon. Sinon PHP : https://windows.php.net/download/ et Composer : https://getcomposer.org/download/

Vérification :

php --version
composer --version

4. Docker Desktop

• Téléchargement : https://www.docker.com/products/docker-desktop/
• Lance Docker Desktop et attends qu'il soit prêt (icône verte).
• Vérification :

docker --version
docker compose version

Sur Windows, active WSL2 si Docker le demande.

---

Étape 1 — Récupérer le code

git clone https://github.com/TakCastel/swor.git
cd swor

(Si le repo est privé, utilise ton URL GitHub habituelle.)

---

Étape 2 — Installation automatique

À la racine du dossier swor :

npm run setup

Cette commande :

• installe les dépendances PHP dans api/ (composer install) ;
• installe les dépendances JavaScript (npm install, workspace front/) ;
• copie les fichiers d'environnement d'exemple s'ils n'existent pas :
  • .env — config Docker Postgres ;
  • api/.env — config Laravel ;
  • front/.env.local — config front (NEXT_PUBLIC_API_URL).

Les valeurs par défaut suffisent pour un premier test local.

---

Étape 3 — Démarrer PostgreSQL

npm run docker:up

Ça lance Postgres dans Docker : base swor, port 54322.

Vérification :

docker ps

Tu dois voir un conteneur swor-db.

---

Étape 4 — Préparer Laravel

cd api
php artisan key:generate
php artisan migrate:fresh --seed
cd ..

• key:generate — clé de chiffrement Laravel (obligatoire) ;
• migrate:fresh --seed — crée les tables et remplit les données de démo (forums, catégories, atlas…).

Erreur de connexion BDD ? Vérifie que Docker tourne (npm run docker:up), attends quelques secondes, réessaie.

---

Étape 5 — Lancer le projet (2 terminaux)

Terminal 1 — API :

npm run dev:api

→ http://localhost:8000

Terminal 2 — Front :

npm run dev:front

→ http://localhost:3000

Ouvre http://localhost:3000 dans ton navigateur.

---

Étape 6 — Vérifier que tout fonctionne

1. Va sur http://localhost:3000
2. Clique Rejoindre / Inscription
3. Crée un compte test
4. Connecte-toi

Si l'inscription passe → front, API et base de données sont OK.

URLs utiles :

URL	Description
http://localhost:3000	Site joueur
http://localhost:8000/up	Santé de l'API Laravel
http://localhost:8000/api/v1/…	Endpoints JSON

---

Commandes utiles

Commande	Description
npm run dev:api	API (serveur + queue + logs)
npm run dev:front	Front Next.js
npm run docker:up	Démarre Postgres
npm run docker:down	Arrête Postgres
npm run test:api	Tests PHPUnit de l'API
npm run lint	Vérification TypeScript du front

Réinitialiser la base locale :

cd api && php artisan migrate:fresh --seed

---

Dépannage

command not found: php ou composer

PHP ou Composer n'est pas installé ou pas dans le PATH. Voir étape 0.3.

command not found: node ou npm

Node n'est pas installé. Voir étape 0.2.

Erreur Docker / port déjà utilisé

Un autre service utilise peut‑être le port 54322. Arrête-le ou modifie POSTGRES_PORT dans .env.

Erreur réseau côté front

• Les deux terminaux doivent tourner (dev:api + dev:front).
• Vérifie front/.env.local :

NEXT_PUBLIC_API_URL=http://localhost:8000

Erreur 419 / CSRF sur l'auth

Utilise localhost partout dans le navigateur (pas 127.0.0.1 d'un côté et localhost de l'autre).

migrate échoue

npm run docker:down
npm run docker:up
# attends ~10 secondes
cd api && php artisan migrate:fresh --seed

---

Structure du repo

swor/
├── api/          ← Backend Laravel (PHP)
├── front/        ← Site joueur (Next.js)
├── docs/         ← Documentation technique (ADR, workflow…)
└── docker-compose.yml   ← Postgres uniquement en dev

Documentation complémentaire dans le repo :

• docs/LARAVEL.md — API, endpoints, auth Sanctum
• docs/WORKFLOW.md — branches, PR, CI
• Architecture-technique — stack et modèle de données (wiki)

---

Besoin d'aide ?

Sur Discord, indique :

1. Ton OS (Windows / Mac / Linux)
2. La commande qui plante
3. Le message d'erreur en entier (copier-coller)