Installation CSWeb Community Platform

Ce guide vous permettra d'installer et de démarrer CSWeb Community Platform en 5 minutes avec Docker.

Prérequis

Système Requis

Installation Docker

# Installation Docker sur Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker
 
# Vérifier l'installation
docker --version
docker compose version

Installation Rapide (5 minutes)

Étape 1 : Cloner le Projet

git clone https://github.com/BOUNADRAME/csweb-community.git
cd csweb-community

Étape 2 : Configuration Environnement

# Copier le fichier .env d'exemple
cp .env.example .env
 
# Éditer .env (IMPORTANT : Changer les mots de passe !)
nano .env  # ou vim, code, etc.

Variables communes (toujours requises, quel que soit le profil) :

# Application
APP_ENV=dev
APP_DEBUG=true
APP_SECRET=CHANGEZ_CETTE_VALEUR_ALEATOIRE

# MySQL Métadonnées (toujours local, ne pas modifier le host)
MYSQL_HOST=mysql
MYSQL_PORT=3306
MYSQL_DATABASE=csweb_metadata
MYSQL_USER=csweb_user
MYSQL_PASSWORD=CHANGEZ_MOT_DE_PASSE
MYSQL_ROOT_PASSWORD=CHANGEZ_MOT_DE_PASSE_ROOT

# Générer un secret aléatoire pour APP_SECRET
openssl rand -hex 32

Étape 3 : Choisir le Profil et Démarrer

Choisissez votre base de données breakout puis le mode (local ou remote).

Par défaut : PostgreSQL en mode local est le profil recommandé pour le développement. Si vous n'êtes pas sûr, restez sur le premier onglet.

# .env — ajouter aux variables communes
BREAKOUT_MODE=local
BREAKOUT_DB_TYPE=postgresql

POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DATABASE=csweb_analytics
POSTGRES_USER=csweb_analytics
POSTGRES_PASSWORD=CHANGEZ_MOT_DE_PASSE

docker compose --profile local-postgres up -d --build

NAME                      STATUS              PORTS
csweb-app                 Up (healthy)        0.0.0.0:8080->80/tcp
csweb-mysql-metadata      Up (healthy)        0.0.0.0:3306->3306/tcp
csweb-postgres-breakout   Up (healthy)        0.0.0.0:5432->5432/tcp

# .env — ajouter aux variables communes
BREAKOUT_MODE=remote
BREAKOUT_DB_TYPE=postgresql

POSTGRES_HOST=votre-serveur-pg.example.com
POSTGRES_PORT=5432
POSTGRES_DATABASE=csweb_analytics
POSTGRES_USER=csweb_analytics
POSTGRES_PASSWORD=votre_mot_de_passe

docker compose up -d csweb mysql

NAME                      STATUS              PORTS
csweb-app                 Up (healthy)        0.0.0.0:8080->80/tcp
csweb-mysql-metadata      Up (healthy)        0.0.0.0:3306->3306/tcp

# Vérifier que tous les conteneurs tournent
docker compose ps

Note : Le conteneur csweb-app peut afficher (unhealthy) avant la configuration initiale. C'est normal car le healthcheck teste l'API qui n'est pas encore configurée.

Étape 4 : Accéder à CSWeb

Ouvrez votre navigateur :

http://localhost:8080

Vous serez automatiquement redirigé vers /setup/ pour la configuration initiale.

Configuration Initiale

Étape 5 : Wizard de Configuration

Après le premier démarrage, CSWeb vous redirige vers le wizard de configuration :

1. Page Requirements (/setup/) :

   • Vérifie PHP 8.1+, extensions PDO, MySQLi, cURL, etc.
   • Tous les checks doivent être verts
   • Cliquer sur "Next"

2. Page Configuration (/setup/configure.php) :

   Champ	Valeur	Description
   Database name	csweb_metadata	Nom de la base MySQL métadonnées
   Hostname	mysql	Nom du conteneur MySQL (pas localhost !)
   Database username	root	Utilisateur MySQL (root nécessaire pour créer la DB)
   Database password	[MYSQL_ROOT_PASSWORD]	Le mot de passe root défini dans .env
   CSWeb admin password	[MOT_DE_PASSE_FORT]	Minimum 8 caractères
   Timezone	UTC	Ou votre fuseau horaire
   Maximum execution time	300	En secondes
   Path to files directory	/var/www/html/files	Chemin par défaut
   CSWeb API URL	http://localhost:8080/api/	Port 8080 accessible depuis le navigateur

   Important : L'API URL doit être http://localhost:8080/api/ (avec le port 8080). C'est l'URL accessible depuis votre navigateur pour accéder à l'API CSWeb. Le port 8080 est le port externe mappé dans Docker qui redirige vers le port 80 interne du conteneur.

3. Cliquer sur "Next" pour finaliser l'installation.

4. Connexion :

   • Username : admin
   • Password : le mot de passe admin choisi à l'étape précédente

Vérification de l'Installation

Vérifier les Drivers

docker compose exec csweb php bin/console csweb:check-database-drivers

Sortie attendue :

Database Drivers Check
======================

 POSTGRESQL   ✅ Available   ✅ pdo, ✅ pdo_pgsql, ✅ pgsql
 MYSQL        ✅ Available   ✅ pdo, ✅ pdo_mysql, ✅ mysqli
 SQLSERVER    ✅ Available   ✅ pdo, ✅ pdo_sqlsrv, ✅ sqlsrv

 [OK] All database types are supported (3/3)

Tester les Connexions

docker compose exec csweb php bin/console csweb:check-database-drivers --test-connections

Tester manuellement

# Depuis votre machine hôte (mode local uniquement)
docker compose exec postgres psql -U csweb_analytics -d csweb_analytics
 
# Ou depuis pgAdmin (si profil dev activé)
# Host: postgres | Port: 5432 | Username: csweb_analytics

Outils de Développement (optionnel)

Ajouter --profile dev pour activer phpMyAdmin et pgAdmin :

# Exemple : PostgreSQL local + outils dev
docker compose --profile local-postgres --profile dev up -d

Prérequis Serveur Distant (mode Remote)

En mode remote, le serveur distant doit être accessible depuis le conteneur CSWeb.

# postgresql.conf
listen_addresses = '*'

# pg_hba.conf
host    all    all    0.0.0.0/0    md5

# Firewall
sudo ufw allow from [IP_SERVEUR_CSWEB] to any port 5432

Architecture Docker

┌───────────────────────────────────────────────────────┐
│                Docker Compose Stack                    │
│                                                        │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────┐  │
│  │  CSWeb   │  │  MySQL   │  │  Breakout DB       │  │
│  │ (Apache) │  │(Metadata)│  │  PostgreSQL :5432  │  │
│  │  :8080   │  │  :3306   │  │  MySQL      :3307  │  │
│  └──────────┘  └──────────┘  │  SQL Server :1433  │  │
│                               └────────────────────┘  │
│            csweb-network (bridge)                      │
│                                                        │
│  ┌──────────┐  ┌──────────┐                           │
│  │phpMyAdmin│  │ pgAdmin  │  (profil dev)             │
│  │  :8081   │  │  :8082   │                           │
│  └──────────┘  └──────────┘                           │
└───────────────────────────────────────────────────────┘

Profils Docker

Volumes Docker

# Lister les volumes
docker volume ls | grep csweb
 
# Backup PostgreSQL
docker compose exec postgres pg_dump -U csweb_analytics csweb_analytics > backup.sql
 
# Backup MySQL metadata
docker compose exec mysql mysqldump -u root -p csweb_metadata > backup_metadata.sql

Commandes Docker Utiles

# Démarrer (adapter le profil selon votre configuration)
docker compose --profile local-postgres up -d
 
# Arrêter tous les services
docker compose down
 
# Redémarrer un service
docker compose restart csweb
 
# Voir les logs
docker compose logs -f csweb
 
# Rebuild après modification du code
docker compose --profile local-postgres up -d --build
 
# Entrer dans le conteneur CSWeb
docker compose exec csweb bash
 
# Vider le cache Symfony
docker compose exec csweb php bin/console cache:clear
 
# Vérifier l'utilisation des ressources
docker stats

Note : Le docker-entrypoint.sh gère automatiquement au démarrage : le vidage du cache Symfony, l'installation du cron scheduler (breakout automatique), et la suppression de la contrainte schema_name si nécessaire.

Troubleshooting

Port 8080 déjà utilisé

# Trouver le processus utilisant le port
sudo lsof -i :8080
 
# OU changer le port dans .env
# CSWEB_PORT=8888

HTTP 500 après configuration

docker compose exec csweb php bin/console cache:clear
docker compose exec csweb chmod -R 777 /var/www/html/var

Access denied lors du setup

Le setup CSWeb nécessite un utilisateur MySQL avec les privilèges CREATE DATABASE. Utilisez root comme Database username dans le wizard de configuration.

API URL - "Failed to connect to localhost port 8080"

L'API URL dans le wizard doit être http://localhost:8080/api/ (port 8080 accessible depuis le navigateur). C'est l'URL publique pour accéder à l'API CSWeb depuis l'extérieur du conteneur Docker.

Container ne démarre pas (unhealthy)

# Vérifier les logs
docker compose logs csweb
docker compose logs postgres
 
# Vérifier la santé
docker inspect csweb-app | grep -A 20 Health

Prochaines Étapes

1. Premier Breakout - Tutorial step-by-step
2. Vérification - Checklist de vérification complète
3. Configuration Multi-DB - Configurer PostgreSQL/MySQL/SQL Server
4. Breakout Sélectif - Guide complet du breakout par dictionnaire

Installation Sans Docker (Legacy)

Si vous ne pouvez pas utiliser Docker, consultez le guide d'installation vanilla :

Installation CSWeb Vanilla (Apache + MySQL manuel)