Installation et configuration¶

Faites fonctionner Stentor localement en moins de cinq minutes. Ce guide couvre la configuration système requise, le déploiement basé sur Docker, la configuration de l'environnement et votre première connexion.

Configuration système requise¶

Avant de commencer, assurez-vous que votre machine répond à ces conditions :

Disponibilité des ports : les ports suivants doivent être libres :

Systèmes d'exploitation pris en charge :

• Linux - recommandé pour les déploiements de production
• macOS -- recommandé pour le développement
• Windows (WSL2) – nécessite Docker Desktop avec le backend WSL2

Démarrage rapide¶

Suivez ces étapes pour passer de zéro à une instance Stentor en cours d'exécution.

1. Clonez le référentiel¶

git clone https://github.com/your-org/stentor.git
cd stentor

# Run inside your WSL2 terminal
git clone https://github.com/your-org/stentor.git
cd stentor

2. Configurer les variables d'environnement¶

cp .env.example .env

Les valeurs par défaut fonctionnent pour le développement local. Voir Configuration de l'environnement ci-dessous pour plus de détails sur chaque variable.

# Generate a random 64-character secret
openssl rand -hex 32

3. Démarrez tous les services¶

docker compose up -d

Docker Compose crée et démarre les quatre services : PostgreSQL, l'API backend, l'interface utilisateur frontend et Adminer. La première construction prend 2 à 3 minutes ; les démarrages suivants sont presque instantanés.

docker compose logs -f

4. Ouvrez l'interface utilisateur¶

Une fois tous les services exécutés :

• Interface utilisateur frontale : http://localhost:3001
• API backend : http://localhost:8082/api/v1
• Administrateur de base de données (administrateur) : http://localhost:8083

5. Connectez-vous¶

Utilisez le compte opérateur seed :

Ces informations d'identification proviennent de database/seed.sql, qui est automatiquement chargé lors de la première initialisation de la base de données.

Configuration de l'environnement¶

Le fichier .env contrôle tous les paramètres d'exécution. Copiez .env.example et personnalisez-le selon vos besoins.

Base de données¶

Authentification¶

Serveur¶

Relais (facultatif)¶

Ces variables ne sont nécessaires que si vous connectez un agent relais.

C2 (facultatif)¶

Ces variables configurent le sous-système Commande & Contrôle.

Services Dockers¶

Stentor fonctionne comme quatre conteneurs Docker orchestrés par Docker Compose.

graph LR
    FE["Frontend<br/>(React + nginx)<br/>:3001"] -->|REST / WebSocket| BE["Backend<br/>(Go + Gin)<br/>:8082"]
    BE -->|SQL| DB["PostgreSQL 16<br/>:5433"]
    ADM["Adminer<br/>:8083"] -->|SQL| DB
    BE -->|SOCKS5| SOCKS[":1080"]

postgres (stentor-c2-db)¶

• Image : postgres:16-alpine
• Port hôte : 5433 (mappé à partir du port de conteneur 5432)
• Volume de données : stentor-c2-postgres-data (persistant après les redémarrages)
• Schéma : database/schema.sql est monté sur /docker-entrypoint-initdb.d/001_schema.sql et s'exécute automatiquement au premier démarrage.
• Données de départ : database/seed.sql crée le compte d'opérateur par défaut
• Health check : pg_isready toutes les 5 secondes avec 5 tentatives

serveur (stentor-c2-backend)¶

• Contexte de construction : server/Dockerfile
• Port hôte : 8082 (mappé à partir du port de conteneur 8080)
• Dépend de : postgres (attend la réussite du contrôle de santé)
• Volumes : ./binaries monté en lecture seule sur /app/binaries pour la génération de payload
• Port supplémentaire : 1080 pour les tunnels proxy SOCKS5

interface (stentor-c2-frontend)¶

• Contexte de construction : ui/Dockerfile
• Port hôte : 3001 (mappé à partir du port de conteneur 80)
• Dépend de : backend
• Sert : Application React conçue pour la production via nginx

administrateur (stentor-c2-adminer)¶

• Image : adminer:latest
• Port hôte : 8083
• Objectif : Navigateur de base de données Web pour le débogage et l'inspection

Première connexion¶

1. Accédez à la page de connexion¶

Ouvrez http://localhost:3001 dans votre navigateur. Vous serez redirigé vers la page de connexion.

2. Entrez les informations d'identification¶

Utilisez le compte opérateur seed :

• E-mail : [email protected]
• Mot de passe : your-password

3. Flux d'authentification¶

Lorsque vous vous connectez, le backend émet deux jetons JWT :

• Jeton d'accès - de courte durée (15 minutes par défaut), envoyé avec chaque requête API dans l'en-tête Authorization
• Jeton d'actualisation – longue durée de vie (7 jours par défaut), utilisé pour obtenir de nouveaux jetons d'accès sans avoir à saisir à nouveau les informations d'identification.

L’interface utilisateur gère automatiquement l’actualisation des jetons. Vous restez connecté jusqu'à l'expiration du jeton d'actualisation.

4. Prochaines étapes¶

Après vous être connecté, vous atterrirez sur le tableau de bord de l'opérateur. Pour une visite guidée de l'interface, continuez vers la page UI Walkthrough.

Gestion de base de données¶

Stentor fournit plusieurs cibles Make pour les opérations de base de données courantes.

Accéder au shell de la base de données¶

make db-shell

Cela ouvre une session psql connectée à la base de données Stentor à l'intérieur du conteneur Docker.

Réinitialiser la base de données¶

# Drop and recreate (preserves the Docker volume)
make db-reset

# Fresh start from schema.sql (drops volume, reseeds)
make db-fresh

Comment le schéma se charge¶

Le docker-compose.yml monte database/schema.sql dans le conteneur PostgreSQL à /docker-entrypoint-initdb.d/001_schema.sql. PostgreSQL exécute automatiquement tous les scripts de ce répertoire à la première initialisation uniquement (lorsque le volume de données est vide). Pour forcer la réinitialisation, supprimez le volume :

docker compose down -v   # removes volumes
docker compose up -d     # fresh start

Mode développement¶

Pour un développement actif, exécutez le backend et le frontend en dehors de Docker avec la prise en charge du rechargement à chaud.

Backend (Go + Air)¶

make dev

Démarre le backend Go avec Air pour une recompilation automatique lors des modifications de fichiers. L'API s'exécute sur http://localhost:8082.

Frontend (Vite HMR)¶

make dev-ui

Démarre le serveur de développement Vite sur http://localhost:3001 avec remplacement du module à chaud. Les modifications apportées aux composants et aux styles React sont reflétées instantanément dans le navigateur.

Les deux à la fois¶

make dev-all

Démarre le backend (Air) et le frontend (Vite) en parallèle.

Configuration du proxy Vite¶

En mode développement, le serveur de développement Vite transmet les requêtes API au backend :

• Les demandes /api/* sont transmises à http://localhost:8082
• /ws/* Les connexions WebSocket sont transférées vers http://localhost:8082

Cela élimine les problèmes CORS lors du développement local : vous accédez à tout via http://localhost:3001.

Dépannage¶

Port déjà utilisé¶

Symptôme : docker compose up échoue avec "le port est déjà alloué".

Correction : Vérifiez ce qui utilise le port et arrêtez-le :

# Find the process using port 5433
lsof -i :5433

# Or kill it directly
kill $(lsof -t -i :5433)

# Find the process using port 5433
netstat -ano | findstr :5433

# Kill by PID (replace 1234 with actual PID)
taskkill /PID 1234 /F

Conflits de ports courants :

La base de données n'est pas prête¶

Symptôme : Les journaux backend affichent des erreurs connection refused dans PostgreSQL.

Correction : Le backend dépend de la vérification de l'état de PostgreSQL, mais si vous avez démarré les services manuellement, la base de données n'est peut-être pas encore prête. Attendez 10 à 15 secondes et vérifiez :

docker compose ps

Assurez-vous que le service postgres affiche l'état healthy. S'il reste unhealthy :

docker compose logs postgres

La connexion échoue avec les informations d'identification par défaut¶

Symptôme : [email protected] / your-password renvoie des « informations d'identification non valides ».

Correction : Les données de départ n'ont peut-être pas été chargées. Reconstruisez la base de données :

make db-fresh

Cela supprime le volume de la base de données, réinitialise à partir de schema.sql et recharge seed.sql.

Incompatibilité de version de Docker Compose¶

Symptôme : Commande docker-compose introuvable ou erreurs de syntaxe dans docker-compose.yml.

Correction : Stentor nécessite Docker Compose v2, qui utilise la commande docker compose (sans le trait d'union) :

# Check your version
docker compose version

# If you get "command not found", install the Compose plugin:
# https://docs.docker.com/compose/install/

La création du conteneur échoue¶

Symptôme : docker compose up --build échoue lors de l'étape de génération Go ou Node.

Correction : Assurez-vous de disposer de suffisamment d'espace disque et de mémoire. Les versions Docker peuvent être gourmandes en ressources :

# Clean up unused Docker resources
docker system prune -f

# Retry the build
docker compose up -d --build

Problèmes de connexion WebSocket¶

Symptôme : L'interface utilisateur affiche « Déconnecté » ou le cockpit ne reçoit pas de mises à jour en temps réel.

Correction : Assurez-vous que le backend est en cours d'exécution et accessible sur le port 8082. En mode développement, le proxy Vite gère automatiquement le transfert WebSocket. En mode Docker, nginx à l'intérieur du conteneur frontend gère le proxy.

# Verify backend is responding
curl http://localhost:8082/api/v1/health