g9-migration/GUIDE-MATRIX.md

Guide Matrix — utilisation et connexion

Objet : rejoindre et administrer le serveur Matrix (Synapse + Element) auto-hébergé. Source : déploiement documenté dans g9-migration/journal.md (Phase 2, 10/10/2026) et DOSSIER-SOFTWARE.md S8. Aucun secret dans ce guide — les identifiants vivent dans Vaultwarden, jamais dans le dépôt (.gitignore : matrix.env, *.key, *.cred).

---

1. État du serveur

Composant	Machine	URL	Rôle
Synapse (homeserver)	G9 (.24)	http://192.168.1.24:8008	Serveur Matrix (API + fédération)
Element Web (client)	G9 (.24)	http://192.168.1.24:8009	Client web, préconfiguré sur le homeserver local
Salon ops	—	!mp7MFx9QbrJ0ARtzw…	Canal d'alertes (watchtower, restic, n8n) — user ops-bot
Cible TLS (Phase 4)	—	https://matrix.folzocorp.fr	Accès sécurisé via Caddy (planifié, non en place)

• Version Synapse : 1.162.0 ; version Element Web : 1.12.30.
• server_name du homeserver : 192.168.1.24 → les identifiants ont la forme @pseudo:192.168.1.24.
• Cible finale documentée : migration Matrix + Jitsi vers le J5040 (.1) (16 Go) — voir DOSSIER-SOFTWARE.md S2.4/S8.

---

2. Connexion

2.1 Element Web (PC, LAN)

1. Ouvrir http://192.168.1.24:8009.
2. Le homeserver est déjà préconfiguré (config.json monté en lecture seule dans le conteneur → base_url: http://192.168.1.24:8008). Rien à saisir.
3. Se connecter avec son compte (§3).

⚠️ En http://IP, Element Web affiche un rond infini (contexte non sécurisé) — lire la section 5. Dépannage avant de diagnostiquer le serveur. Fix recommandé : tunnel localhost (§5.2) ou TLS Phase 4.

2.2 Element Android (téléphone)

1. Installer Element (Play Store / F-Droid).
2. À l'écran de bienvenue : Modifier le serveur d'accueil (Changer de serveur).
3. Saisir http://192.168.1.24:8008 → Suivant → Se connecter.
4. Nom d'utilisateur = le pseudo sans le domaine (ex. effi, pas @effi:192.168.1.24) + mot de passe.

2.3 Element Desktop (PC)

1. Installer Element Desktop (le navigateur n'est pas concerné par la restriction de contexte sécurisé).
2. Écran de connexion → Modifier le serveur d'accueil → http://192.168.1.24:8008.

2.4 Accès depuis l'extérieur (hors LAN)

Matrix n'est pas exposé sur Internet (volontairement). Deux voies :

Voie	Comment
WireGuard (J5040 .1)	Se connecter au VPN depuis le téléphone/PC portable → le LAN .1/24 est atteignable → ouvrir http://192.168.1.24:8009 (Android : saisir directement le homeserver dans l'app)
TLS Phase 4 (à faire)	Caddy + matrix.folzocorp.fr → l'app Element utilise https://matrix.folzocorp.fr, accessible de façon sécurisée

---

3. Création de compte

L'inscription publique est désactivée (pas de self-registration sur un serveur privé). Les comptes se créent côté serveur, en SSH sur le G9 (.24).

3.1 Prérequis : un compte admin Synapse

Si aucun admin n'existe, en créer un via le conteneur Synapse :

# sur .24 — trouver le nom du conteneur
docker ps --format '{{.Names}}' | grep -i synapse

# créer un utilisateur admin (le script lit le shared secret du homeserver.yaml)
docker exec -it <conteneur_synapse> register_new_matrix_user \
  -c /data/homeserver.yaml -a -u <ADMIN> -p '<MOT_DE_PASSE_ADMIN>'

Si register_new_matrix_user refuse (pas de registration_shared_secret dans homeserver.yaml) : l'ajouter via sudo dans /data/homeserver.yaml (registration_shared_secret: <SECRET_ALEATOIRE>, généré par openssl rand -hex 32), restart du conteneur, relancer la commande, puis retirer le secret et restart à nouveau. Même pattern que room_creation: true (journal 2026-10-09). Stocker <MOT_DE_PASSE_ADMIN> dans Vaultwarden.

3.2 Créer les comptes (famille, bots) via l'API admin

Étape 1 — obtenir un token admin (login avec le compte admin) :

curl -s -X POST 'http://192.168.1.24:8008/_matrix/client/v3/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "auth": {
      "type": "m.login.password",
      "identifier": { "type": "m.id.user", "user": "<ADMIN>" },
      "passphrase": "<MOT_DE_PASSE_ADMIN>"
    }
  }'
# → réponse JSON : récupérer "access_token" (= <TOKEN_ADMIN>)

Étape 2 — créer l'utilisateur (API admin v2, PUT = enregistrement) :

curl -s -X PUT 'http://192.168.1.24:8008/_synapse/admin/v2/users/@<PSEUDO>:192.168.1.24' \
  -H "Authorization: Bearer <TOKEN_ADMIN>" \
  -H 'Content-Type: application/json' \
  -d '{
    "password": "<MOT_DE_PASSE_UTILISATEUR>",
    "display_name": "<Nom affiché>",
    "admin": false
  }'
# → 201 Created = compte créé

• admin: true pour un second administrateur, false pour la famille/bots.
• Le pseudo est en minuscules, sans espaces ni accents (règle Matrix).

3.3 Première connexion + chiffrement (E2E)

1. Ouvrir Element (§2), se connecter avec @<PSEUDO>:192.168.1.24 (Web/Desktop : pseudo seul suffit).
2. Element demande une phrase de passe de récupération (secure backup) → la noter hors-ligne (papier), c'est la porte de sortie du chiffrement.
3. Vérifier ses sessions : Paramètres → Sécurité → Vérification (QR code entre téléphone et PC) pour valider le chiffrement de bout en bout.

3.4 Désinscription / suppression

• Désactiver un compte (propre, conserve la trace) :

  curl -s -X POST 'http://192.168.1.24:8008/_synapse/admin/v1/deactivate/<PSEUDO>' \
    -H "Authorization: Bearer <TOKEN_ADMIN>" \
    -H 'Content-Type: application/json' \
    -d '{ "erase": true }'
  

• Vérifier que l'inscription publique reste fermée dans homeserver.yaml : disable_registration: true (ne pas activer enable_registration sans point d'accès protégé).

---

4. Usage type (rappel du plan, S8)

Salon	Contenu
Famille	Messagerie quotidienne du foyer (complément de WhatsApp, pas un remplacement), visio Jitsi intégrée à Element
Ops	Alertes machine : watchtower (MAJ images), restic (backup G9), n8n — via ops-bot
hermes (prévu)	Salon où la famille parle à Effi (assistant, Phase 3 du second cerveau)

---

5. Dépannage

5.1 Le rond infini dans Element Web (cause racine documentée)

Symptôme : page noire, spinner infini sur http://192.168.1.24:8009. Console (F12) :

Browser missing feature: 'crypto'
Browser missing feature: 'securecontext'
Error initialising Matrix session TypeError: window.crypto.randomUUID is not a function

Cause : Element ≥ 1.12 exige un contexte sécurisé (HTTPS, localhost ou file:). En http://<IP>, le navigateur coupe crypto.randomUUID → Element n'arrive pas à initialiser la session. Le serveur n'y est pas pour rien.

Anodins (à ne pas poursuivre) : 404 config.<host>.json (config optionnelle par hôte) et 404 /_matrix/client/v1/auth_metadata (endpoint optionnel).

Cause secondaire : un vieux service worker peut garder en cache une config obsolète (la config cassée « matrix.org » d'avant le fix du 10/10). Nettoyage : F12 → Application → Service Workers → Unregister, puis Storage → Clear site data, puis Ctrl+Maj+R.

5.2 Workaround sans TLS : tunnel localhost

localhost est un contexte sécurisé → Element fonctionne. Depuis le PC :

ssh -L 8009:192.168.1.24:8009 -L 8008:192.168.1.24:8008 <user>@192.168.1.24
# puis ouvrir http://localhost:8009

5.3 Fix définitif : TLS (Phase 4)

Caddy + matrix.folzocorp.fr (même pattern que obsidian.folzocorp.fr, journal Phase 4) → Element Web servi en HTTPS, spinner résolu, accès distant propre.

5.4 Commandes de diagnostic (côté serveur, tout doit répondre)

# 1) API vivante → JSON avec "versions":[...] (200)
curl -s http://192.168.1.24:8008/_matrix/client/versions

# 2) Element servi + config correcte → 200 + base_url = http://192.168.1.24:8008
curl -s http://192.168.1.24:8009/ -o /dev/null -w '%{http_code}\n'
curl -s http://192.168.1.24:8009/config.json

# 3) CORS (sans lui, Element web est muet) → Access-Control-Allow-Origin: *
curl -s -D - -o /dev/null -H "Origin: http://192.168.1.24:8009" \
  http://192.168.1.24:8008/_matrix/client/versions | grep -i access-control

# 4) Conteneurs
docker ps --format '{{.Names}}\t{{.Status}}' | grep -Ei 'synapse|element'

Résultats vérifiés le 11/10/2026 : 1) 200 + versions r0.0.1→v1.12 ; 2) 200 + base_url: http://192.168.1.24:8008 ; 3) Access-Control-Allow-Origin: * ; 4) synapse Synapse/1.162.0 UP. Si ces 4 tests passent et qu'Element tourne en rond → problème 100 % navigateur (§5.1/5.2).

5.5 Alertes ops absentes du salon ops

• Vérifier le token ops-bot : côté G9, /etc/restic/matrix.env (root, 600) pour restic ; workflow n8n « Watchtower Notification » pour les MAJ d'images.
• Test d'envoi direct :

  curl -s -X POST 'http://192.168.1.24:8008/_matrix/client/v3/rooms/!mp7MFx9QbrJ0ARtzw…/send/m.room.message/test1' \
    -H "Authorization: Bearer <TOKEN_OPS_BOT>" \
    -H 'Content-Type: application/json' \
    -d '{"msgtype":"m.text","body":"test alerte"}'
  # → 200 + {"event_id":"$…"}
  

---

6. Sécurité (règles du projet)

Règle	Application Matrix
Secrets hors dépôt	Token admin, mot de passe admin, matrix.env → Vaultwarden / root only, jamais git
Pas d'exposition Internet	Accès LAN ou WireGuard ; TLS Phase 4 pour l'exposition contrôlée
2FA	À activer sur les comptes admin (S9 : 2FA sur tous les services exposés)
Comptes famille	admin: false, mot de passe unique par personne, phrase de récupération E2E notée hors-ligne

---

Guide créé le 11/10/2026 — état vérifié ce jour sur .24 (Synapse 1.162.0, Element 1.12.30). À réaligner quand Matrix migrera vers le J5040 (.1) et que matrix.folzocorp.fr (Caddy TLS) sera en place.