Installation - Humanix Académie Community Edition

Ce guide te permet d'installer Humanix Académie en self-host sur ton infrastructure. Trois modes sont supportés :

Docker Compose (recommandé pour la majorité des cas)
Bare-metal (Node.js + PostgreSQL natifs)
Kubernetes (production multi-nœuds)

Temps estimé : 10 à 30 minutes selon le mode et ton expérience.

Prérequis

Composant	Version minimale	Recommandée
CPU	2 vCPU	4 vCPU
RAM	2 Go	4 Go
Disque SSD	5 Go	20 Go
OS hôte	Linux 5.10+ / macOS 12+ / Windows 11 (WSL2)	Ubuntu 24.04 LTS
Docker (mode 1)	24.0+	26+
Docker Compose (mode 1)	v2.20+	v2.27+
Node.js (mode 2)	20.10+	20.x LTS
PostgreSQL (mode 2)	14+	16
Redis (optionnel, sessions)	-	7.2

Mode 0 - Quickstart dev avec HTTPS local (3 minutes) ⚡

Pour les développeurs qui veulent juste lancer l'app localement avec un certificat TLS valide (pas de warning "site non sécurisé" dans le browser, NextAuth fonctionne en HTTPS comme en prod).

git clone https://github.com/Humanix-Cybersecurity/Humanix-Academie.git
cd humanix-academie
./scripts/start.sh

C'est tout. Le script :

Détecte l'OS (macOS / Linux)
Vérifie Docker (OrbStack ou Docker Desktop sur Mac, Docker Engine sur Linux). Propose l'installation via Homebrew / curl si manquant.
Installe mkcert (pour le certificat local trust-safe)
Génère un cert TLS signé par le CA local mkcert pour humanix.local
- localhost (cf. infra/haproxy/certs/)
Ajoute 127.0.0.1 humanix.local à /etc/hosts (avec sudo)
Crée un .env minimal en DEMO_MODE=true avec AUTH_URL=https://humanix.local
Active la config HAProxy dev (HTTPS sur 443 + redirect HTTP→HTTPS)
Lance docker compose up -d (avec override docker-compose.dev.yml)

À la fin, ouvre https://humanix.local dans ton browser. Aucune popup "site non sécurisé" : le CA mkcert a été ajouté au trust store OS.

Commandes utiles

./scripts/start.sh             # démarrage complet (idempotent)
./scripts/start.sh --restart   # rebuild + restart
./scripts/start.sh --stop      # arrête tous les containers
./scripts/start.sh --logs      # tail des logs en direct
./scripts/start.sh --reset     # ⚠️ détruit la BDD et redémarre from scratch

Pourquoi HTTPS en dev ?

NextAuth v5 utilise des cookies __Secure-* qui ne fonctionnent que sur HTTPS. Sans certificat valide, certains flows d'auth (magic link, OAuth Google/Microsoft) cassent silencieusement. Le script start.sh reproduit les conditions de prod (HTTPS + hostname dédié) avec un cert local trust-safe, ce qui évite des heures de debug "ça marche en prod, pas en local".

Notes par OS

macOS : OrbStack est recommandé (plus léger que Docker Desktop, intégration native, ouverture instantanée). brew install orbstack puis lancer une fois l'app pour init.

Linux : le script suppose Docker Engine + plugin Compose v2 (docker compose, pas docker-compose). mkcert doit être installé manuellement (cf. instructions affichées par le script).

Windows : utilise WSL2 + Ubuntu, puis lance ./scripts/start.sh dedans. Le script ne supporte pas PowerShell / cmd directement.

Mode 1 - Docker Compose (recommandé)

C'est le mode le plus simple et le plus reproductible.

Étape 1 - Clone le repo

git clone https://github.com/humanix-cybersecurity/humanix-academie.git
cd humanix-academie

Étape 2 - Configure tes variables d'environnement

cp .env.example .env

Édite .env avec ton éditeur préféré et renseigne au minimum :

# Identité de ton instance (URL publique HTTPS recommandée en prod)
NEXT_PUBLIC_APP_URL=https://academie.tonentreprise.fr

# Base de données (Docker Compose la fournit en interne)
DATABASE_URL=postgresql://humanix:CHANGEME@postgres:5432/humanix?schema=public

# Secret de signature des sessions (32+ caractères aléatoires)
# Génère-le avec : openssl rand -base64 32
AUTH_SECRET=remplace-moi-par-un-secret-genere

# Email transactionnel (magic link, notifications)
SCALEWAY_TEM_TOKEN=re_xxxxxxxxxxxxxxxxxxxxx
SMTP_FROM=noreply@tonentreprise.fr

Pour la liste complète des variables, voir configuration.md.

Étape 3 - Démarre la stack

docker compose up -d

Cela lance trois services :

postgres - base de données
app - application Next.js (port 3000)
caddy - reverse proxy avec TLS auto Let's Encrypt (ports 80 et 443)

Étape 4 - Initialise la base de données

# Applique les migrations
docker compose exec app npx prisma migrate deploy

# Seed initial (1 tenant demo + 1 admin)
docker compose exec app npx prisma db seed

# Applique les REVOKE chirurgicaux pour le rôle Postgres read-only
# (Sprint sécurité 2 - defense en profondeur Least Privilege)
docker compose exec postgres psql -U humanix -d humanix \
  < prisma/sql/post-migration-grants.sql

🛡️ Note sécurité - L'image Postgres custom humanix-postgres:secured provisionne automatiquement un rôle Postgres read-only au premier boot (mécanisme Least Privilege). Sur instance existante, applique prisma/sql/setup-readonly-role.sql manuellement.

Étape 5 - Premier accès

Ouvre https://academie.tonentreprise.fr (ou http://localhost:3000 en local).

Identifiants admin par défaut :

docker compose logs app | grep "Initial admin"
# Tu verras : Initial admin: admin@example.com / mot-de-passe-temporaire

Connecte-toi, change immédiatement le mot de passe, puis crée tes utilisateurs réels via /admin/utilisateurs.

Mode 2 - Bare-metal (Node + PostgreSQL natifs)

Pour les environnements où Docker n'est pas autorisé ou pour la performance maximale.

Étape 1 - Installe Node.js 20

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Vérification
node --version  # v20.x.x
npm --version   # 10.x.x

Étape 2 - Installe PostgreSQL 16

sudo apt-get install -y postgresql-16 postgresql-contrib-16

# Crée la base et l'utilisateur
sudo -u postgres psql <<'EOF'
CREATE USER humanix WITH PASSWORD 'CHANGEME';
CREATE DATABASE humanix OWNER humanix;
GRANT ALL PRIVILEGES ON DATABASE humanix TO humanix;
EOF

Étape 3 - Clone et configure

git clone https://github.com/humanix-cybersecurity/humanix-academie.git
cd humanix-academie
cp .env.example .env
# Édite .env (cf. Mode 1 étape 2)

Étape 4 - Installe les dépendances et build

npm ci --omit=dev
npx prisma migrate deploy
npx prisma generate
npm run build

Étape 5 - Démarre l'application

En production, utilise un superviseur de processus (systemd, pm2, etc.) :

# Test rapide en foreground
npm start
# → http://localhost:3000

Exemple de service systemd (/etc/systemd/system/humanix.service) :

[Unit]
Description=Humanix Académie
After=network.target postgresql.service

[Service]
Type=simple
User=humanix
WorkingDirectory=/opt/humanix-academie
EnvironmentFile=/opt/humanix-academie/.env
ExecStart=/usr/bin/node node_modules/.bin/next start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now humanix
sudo systemctl status humanix

Étape 6 - Reverse proxy (nginx ou Caddy)

Pour exposer l'app sur le port 443 avec TLS :

Caddy (recommandé, TLS auto) :

academie.tonentreprise.fr {
    reverse_proxy localhost:3000
}

Nginx :

server {
    listen 443 ssl http2;
    server_name academie.tonentreprise.fr;

    ssl_certificate /etc/letsencrypt/live/academie.tonentreprise.fr/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/academie.tonentreprise.fr/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Mode 3 - Kubernetes (production multi-nœuds)

Pour les déploiements production exigeants (haute dispo, scaling horizontal, multi-AZ).

Helm chart (recommandé)

Un Helm chart officiel sera publié pour la version 1.1 (Q3 2026). En attendant, des manifestes Kubernetes de référence sont fournis dans infra/kubernetes/ :

kubectl create namespace humanix
kubectl apply -n humanix -k infra/kubernetes/overlays/production

Couvre :

Deployment Next.js (3 réplicas par défaut)
StatefulSet PostgreSQL (1 réplica + PVC)
Service ClusterIP + Ingress (cert-manager)
Secret + ConfigMap pour les variables d'env
HPA (scale 2-10 selon CPU)

Recommandations production K8s

PostgreSQL : utilise un service managé (AWS RDS, Scaleway DB, OVHcloud Managed Database, CrunchyData) plutôt que le StatefulSet
Sessions : ajoute Redis pour partager les sessions entre pods (sinon sticky sessions obligatoires sur l'Ingress)
Stockage : si tu actives les uploads (modules contributeurs avec médias), utilise un S3-compatible (Scaleway Object Storage, OVHcloud Cold Storage)
Monitoring : Prometheus + Grafana, dashboard fourni dans infra/grafana/humanix-overview.json

Durcissement production

1. Variables d'environnement sensibles

AUTH_SECRET : 32+ caractères aléatoires, jamais committé en git
DATABASE_URL : utilise un user PostgreSQL dédié avec privilèges minimaux (SELECT, INSERT, UPDATE, DELETE uniquement, pas de CREATE ni DROP)
Stockage : variables dans un secret manager (Vault, AWS Secrets Manager, Scaleway Secrets), jamais dans le .env du serveur en clair

2. TLS et HSTS

TLS 1.2 minimum (1.3 recommandé)
HSTS activé avec max-age=31536000
CSP strict : frame-ancestors 'none', default-src 'self'
Configuration de référence dans infra/caddy/Caddyfile.production

3. Réseau

PostgreSQL JAMAIS exposé sur Internet (port 5432 fermé au public)
Réseau Docker segmenté : frontend (web + caddy) et backend (web + db)
Firewall hôte (ufw, firewalld) qui ne laisse passer que 80, 443, 22

4. Sauvegardes

Sauvegarde quotidienne PostgreSQL chiffrée (pg_dump + gpg)
Rétention 7 jours minimum, 30 jours recommandé
Test de restauration mensuel (procédure dans infra/scripts/backup-test.sh)
Stockage off-site (S3 différent du serveur ou région différente)

5. Logs et monitoring

Logs centralisés (Loki, ELK, Graylog) avec rotation 30 jours
Alerting sur :
- Tentatives d'authentification en échec > 10/min
- Erreurs 5xx > 1 % des requêtes
- Latence p95 > 2s
- Espace disque < 20 %
Healthcheck endpoint : /api/health (retourne 200 OK si tout va bien)

6. Mises à jour

Abonne-toi aux notifications GitHub du repo (Watch → Releases only)
Applique les patches sécurité sous 7 jours pour Critique/Élevé (cf. SECURITY.md)
Procédure : voir upgrade.md

Vérification post-installation

Une fois installée, valide ton instance avec ces 5 tests :

Accès web : curl -I https://academie.tonentreprise.fr → 200 OK
TLS valide : curl -vI https://... → certificat OK
Healthcheck : curl https://academie.tonentreprise.fr/api/health → {"status":"ok"}
Connexion admin : login avec le compte initial
Création utilisateur : crée un utilisateur de test, vérifie l'envoi du magic link par email

Si l'un de ces tests échoue, voir faq.md section troubleshooting.

Désinstallation

# Mode Docker Compose
docker compose down -v   # Le -v supprime AUSSI les volumes (donc la DB)

# Mode bare-metal
sudo systemctl stop humanix
sudo systemctl disable humanix
sudo rm /etc/systemd/system/humanix.service
sudo -u postgres dropdb humanix
sudo -u postgres dropuser humanix
sudo rm -rf /opt/humanix-academie

Avant désinstallation : pense à exporter ton rapport de conformité PDF et à sauvegarder ta base si tu veux garder les données (RGPD).

Aide

Questions self-host : GitHub Discussions Q&A
Bugs : GitHub Issues
Discord communautaire : ouverture après le launch OSS du 26 mai 2026
Cloud managé (sans installation) : https://humanix-cybersecurity.fr/tarifs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Installation - Humanix Académie Community Edition

Prérequis

Mode 0 - Quickstart dev avec HTTPS local (3 minutes) ⚡

Commandes utiles

Pourquoi HTTPS en dev ?

Notes par OS

Mode 1 - Docker Compose (recommandé)

Étape 1 - Clone le repo

Étape 2 - Configure tes variables d'environnement

Étape 3 - Démarre la stack

Étape 4 - Initialise la base de données

Étape 5 - Premier accès

Mode 2 - Bare-metal (Node + PostgreSQL natifs)

Étape 1 - Installe Node.js 20

Étape 2 - Installe PostgreSQL 16

Étape 3 - Clone et configure

Étape 4 - Installe les dépendances et build

Étape 5 - Démarre l'application

Étape 6 - Reverse proxy (nginx ou Caddy)

Mode 3 - Kubernetes (production multi-nœuds)

Helm chart (recommandé)

Recommandations production K8s

Durcissement production

1. Variables d'environnement sensibles

2. TLS et HSTS

3. Réseau

4. Sauvegardes

5. Logs et monitoring

6. Mises à jour

Vérification post-installation

Désinstallation

Aide

Uh oh!

FilesExpand file tree

installation.md

Latest commit

History

installation.md

File metadata and controls

Installation - Humanix Académie Community Edition

Prérequis

Mode 0 - Quickstart dev avec HTTPS local (3 minutes) ⚡

Commandes utiles

Pourquoi HTTPS en dev ?

Notes par OS

Mode 1 - Docker Compose (recommandé)

Étape 1 - Clone le repo

Étape 2 - Configure tes variables d'environnement

Étape 3 - Démarre la stack

Étape 4 - Initialise la base de données

Étape 5 - Premier accès

Mode 2 - Bare-metal (Node + PostgreSQL natifs)

Étape 1 - Installe Node.js 20

Étape 2 - Installe PostgreSQL 16

Étape 3 - Clone et configure

Étape 4 - Installe les dépendances et build

Étape 5 - Démarre l'application

Étape 6 - Reverse proxy (nginx ou Caddy)

Mode 3 - Kubernetes (production multi-nœuds)

Helm chart (recommandé)

Recommandations production K8s

Durcissement production

1. Variables d'environnement sensibles

2. TLS et HSTS

3. Réseau

4. Sauvegardes

5. Logs et monitoring

6. Mises à jour

Vérification post-installation

Désinstallation

Aide