first
This commit is contained in:
Gilles Soulier
@@ -0,0 +1,273 @@
|
||||
<!--
|
||||
Created by: Claude
|
||||
Date: 2026-01-02
|
||||
Purpose: Documentation du serveur Mesh
|
||||
Refs: server/CLAUDE.md
|
||||
-->
|
||||
|
||||
# Mesh Server
|
||||
|
||||
Serveur de control plane pour la plateforme Mesh.
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Docker (Recommandé)
|
||||
|
||||
```bash
|
||||
# Copier et configurer l'environnement
|
||||
cp .env.example .env
|
||||
# Éditer .env avec vos valeurs (notamment MESH_JWT_SECRET)
|
||||
|
||||
# Construire l'image Docker
|
||||
docker build -t mesh-server .
|
||||
|
||||
# Lancer le serveur
|
||||
docker run -d --name mesh-server -p 8000:8000 --env-file .env mesh-server
|
||||
|
||||
# Voir les logs
|
||||
docker logs mesh-server -f
|
||||
```
|
||||
|
||||
### Option 2: Installation Locale
|
||||
|
||||
**Note**: Nécessite Python 3.12+ (Python 3.13 non supporté actuellement)
|
||||
|
||||
```bash
|
||||
# Créer un environnement virtuel
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
|
||||
# Installer les dépendances
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Copier et configurer l'environnement
|
||||
cp .env.example .env
|
||||
# Éditer .env avec vos valeurs
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Éditer le fichier `.env`:
|
||||
|
||||
```bash
|
||||
# Serveur
|
||||
MESH_PUBLIC_URL=http://localhost:8000
|
||||
MESH_JWT_SECRET=your-secret-key-min-32-chars
|
||||
|
||||
# Gotify
|
||||
GOTIFY_URL=http://gotify:8080
|
||||
GOTIFY_TOKEN=your-gotify-token
|
||||
|
||||
# TURN/STUN
|
||||
STUN_URL=stun:stun.l.google.com:19302
|
||||
TURN_HOST=turn.example.com
|
||||
|
||||
# Base de données
|
||||
DATABASE_URL=sqlite:///./mesh.db
|
||||
```
|
||||
|
||||
## Démarrage
|
||||
|
||||
### Avec Docker
|
||||
```bash
|
||||
# Le serveur est déjà lancé après docker run
|
||||
# Pour voir les logs:
|
||||
docker logs mesh-server -f
|
||||
|
||||
# Pour arrêter:
|
||||
docker stop mesh-server
|
||||
|
||||
# Pour redémarrer:
|
||||
docker start mesh-server
|
||||
```
|
||||
|
||||
### En local
|
||||
```bash
|
||||
# Lancer le serveur en mode développement
|
||||
python3 -m uvicorn src.main:app --reload
|
||||
|
||||
# Ou avec le script
|
||||
python3 -m src.main
|
||||
```
|
||||
|
||||
Le serveur démarre sur http://localhost:8000
|
||||
|
||||
## API Documentation
|
||||
|
||||
Documentation interactive disponible sur:
|
||||
- Swagger UI: http://localhost:8000/docs
|
||||
- ReDoc: http://localhost:8000/redoc
|
||||
|
||||
## Endpoints Principaux
|
||||
|
||||
### Authentification
|
||||
- `POST /api/auth/register` - Créer un compte
|
||||
- `POST /api/auth/login` - Se connecter
|
||||
- `GET /api/auth/me` - Informations utilisateur
|
||||
- `POST /api/auth/capability` - Demander un capability token
|
||||
|
||||
### Rooms
|
||||
- `POST /api/rooms/` - Créer une room
|
||||
- `GET /api/rooms/` - Lister mes rooms
|
||||
- `GET /api/rooms/{room_id}` - Détails d'une room
|
||||
- `GET /api/rooms/{room_id}/members` - Membres d'une room
|
||||
|
||||
### WebSocket
|
||||
- `WS /ws?token=JWT_TOKEN` - Connexion temps réel
|
||||
|
||||
## Structure du Projet
|
||||
|
||||
```
|
||||
server/
|
||||
├── src/
|
||||
│ ├── main.py # Point d'entrée
|
||||
│ ├── config.py # Configuration
|
||||
│ ├── api/ # Routes API REST
|
||||
│ │ ├── auth.py # Authentification
|
||||
│ │ └── rooms.py # Gestion des rooms
|
||||
│ ├── auth/ # Authentification & sécurité
|
||||
│ │ ├── security.py # JWT, hashing, capability tokens
|
||||
│ │ ├── schemas.py # Schémas Pydantic
|
||||
│ │ └── dependencies.py # Dépendances FastAPI
|
||||
│ ├── db/ # Base de données
|
||||
│ │ ├── base.py # Configuration SQLAlchemy
|
||||
│ │ └── models.py # Modèles ORM
|
||||
│ └── websocket/ # WebSocket temps réel
|
||||
│ ├── manager.py # Gestionnaire de connexions
|
||||
│ ├── events.py # Types d'événements
|
||||
│ └── handlers.py # Handlers d'événements
|
||||
├── alembic/ # Migrations
|
||||
├── tests/ # Tests
|
||||
├── requirements.txt
|
||||
├── .env.example
|
||||
└── Dockerfile
|
||||
```
|
||||
|
||||
## Développement
|
||||
|
||||
### Tests
|
||||
|
||||
```bash
|
||||
# Test de l'API (avec serveur lancé)
|
||||
python3 test_api.py
|
||||
|
||||
# Tests unitaires
|
||||
pytest tests/
|
||||
```
|
||||
|
||||
### Migrations
|
||||
|
||||
```bash
|
||||
# Créer une migration
|
||||
alembic revision --autogenerate -m "Description"
|
||||
|
||||
# Appliquer les migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Revenir en arrière
|
||||
alembic downgrade -1
|
||||
```
|
||||
|
||||
### Linting
|
||||
|
||||
```bash
|
||||
# Type checking
|
||||
mypy src/
|
||||
|
||||
# Formatage
|
||||
black src/
|
||||
|
||||
# Linting
|
||||
flake8 src/
|
||||
```
|
||||
|
||||
## Événements WebSocket
|
||||
|
||||
Voir [docs/protocol_events_v_2.md](../docs/protocol_events_v_2.md) pour le protocole complet.
|
||||
|
||||
### Exemples
|
||||
|
||||
**system.hello**:
|
||||
```json
|
||||
{
|
||||
"type": "system.hello",
|
||||
"from": "peer_123",
|
||||
"to": "server",
|
||||
"payload": {
|
||||
"peer_type": "client",
|
||||
"version": "0.1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**room.join**:
|
||||
```json
|
||||
{
|
||||
"type": "room.join",
|
||||
"from": "peer_123",
|
||||
"to": "server",
|
||||
"payload": {
|
||||
"room_id": "room_uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**chat.message.send**:
|
||||
```json
|
||||
{
|
||||
"type": "chat.message.send",
|
||||
"from": "peer_123",
|
||||
"to": "server",
|
||||
"payload": {
|
||||
"room_id": "room_uuid",
|
||||
"content": "Hello world"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sécurité
|
||||
|
||||
- Tous les endpoints protégés nécessitent un JWT Bearer token
|
||||
- Les capability tokens ont un TTL court (60-180s)
|
||||
- Les mots de passe sont hashés avec bcrypt
|
||||
- Les WebSocket nécessitent un token JWT valide
|
||||
|
||||
Voir [docs/security.md](../docs/security.md) pour plus de détails.
|
||||
|
||||
## Variables d'Environnement
|
||||
|
||||
| Variable | Description | Défaut |
|
||||
|----------|-------------|--------|
|
||||
| MESH_PUBLIC_URL | URL publique du serveur | http://localhost:8000 |
|
||||
| MESH_HOST | Host d'écoute | 0.0.0.0 |
|
||||
| MESH_PORT | Port d'écoute | 8000 |
|
||||
| MESH_JWT_SECRET | Secret pour JWT | (requis) |
|
||||
| MESH_JWT_ALGORITHM | Algorithme JWT | HS256 |
|
||||
| MESH_JWT_ACCESS_TOKEN_EXPIRE_MINUTES | Expiration token | 120 |
|
||||
| GOTIFY_URL | URL Gotify | (requis) |
|
||||
| GOTIFY_TOKEN | Token Gotify | (requis) |
|
||||
| STUN_URL | URL STUN | stun:stun.l.google.com:19302 |
|
||||
| TURN_HOST | Host TURN | (optionnel) |
|
||||
| TURN_PORT | Port TURN | 3478 |
|
||||
| DATABASE_URL | URL base de données | sqlite:///./mesh.db |
|
||||
| LOG_LEVEL | Niveau de log | INFO |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Erreur de connexion à la DB
|
||||
|
||||
```bash
|
||||
# Vérifier que la DB existe
|
||||
ls -la mesh.db
|
||||
|
||||
# Créer les tables manuellement
|
||||
python -c "from src.db.base import Base, engine; Base.metadata.create_all(engine)"
|
||||
```
|
||||
|
||||
### Token JWT invalide
|
||||
|
||||
Vérifier que `MESH_JWT_SECRET` est défini et identique entre serveur et client.
|
||||
|
||||
### WebSocket déconnecté immédiatement
|
||||
|
||||
Vérifier que le token JWT est passé en query param: `/ws?token=YOUR_TOKEN`
|
||||
Reference in New Issue
Block a user