Fediclé

Version actuelle : v0.4.18-alpha

Fediclé est une plateforme fédérée basée sur ActivityPub permettant la création d'un réseau de confiance décentralisé via des signatures OpenPGP. Elle permet de certifier l'identité des membres du Fédivers, créant une toile de confiance (Web of Trust) vérifiable.

---

📦 Guide d'Installation (Serveur / Production)

Ce guide est destiné aux administrateurs souhaitant héberger leur propre instance Fediclé rapidement. Aucune connaissance en Node.js n'est requise.

Prérequis

• Un serveur Linux (VPS, Dédié...)
• Docker et Docker Compose installés
• Un nom de domaine pointant vers l'adresse IP de votre serveur
• Les ports 80 (HTTP) et 443 (HTTPS) ouverts

1. Installation

# 1. Récupérer le projet
git clone https://forgejo.votre-instance.tld/fedicle/fedicle.git
cd fedicle

# 2. Se placer sur la version officielle (Tag)
git checkout tags/v0.4.18-alpha

# 3. Préparer la configuration
cp .env.example .env

# 4. Éditer la configuration (OBLIGATOIRE)
# Suivez les instructions dans le fichier pour définir :
# - Votre FEDICLE_DOMAIN (ex: social.mon-domaine.tld)
# - Votre ADMIN_EMAIL (utilisé pour SSL et contact)
# - Vos secrets de sécurité (JWT_SECRET, ENCRYPTION_SECRET)
#
# NOTE : La variable FEDICLE_DOMAIN remplace l'ancienne variable DOMAINE.
# CONSEIL : Générez vos secrets avec la commande : openssl rand -base64 48
nano .env

# 5. Lancer l'application
docker compose up -d --build --remove-orphans

C'est tout ! L'application sera accessible sur https://votre-domaine.tld. Le certificat HTTPS est généré et renouvelé automatiquement par le service edge

1.1 Création du compte administrateur

Par sécurité, Fediclé ne crée pas de compte administrateur par défaut. Voici la marche à suivre :

1. Rendez-vous sur votre instance (https://votre-domaine.tld).

2. Créez votre compte normalement (Générer une identité).

3. Une fois votre compte créé, récupérez votre nom d'utilisateur (ex: alice).

4. Exécutez la commande suivante sur votre serveur pour vous donner les droits d'administration :

   docker exec -it fedicle-engine pnpm run --filter "@fedicle/server" promote-admin votre_nom_d_utilisateur
   

Vous aurez alors accès au menu Administration dans l'interface de Fediclé.

1.2 Utiliser son propre Reverse Proxy (Optionnel)

Si vous avez déjà un serveur web (Nginx, Caddy, HAProxy) sur votre machine hôte, vous pouvez utiliser votre infrastructure existante :

1. Désactivez le conteneur edge par défaut dans votre fichier .env :

   COMPOSE_PROFILES=none
   

2. Activez l'exposition des ports ou la connexion au réseau en copiant l'un des deux modèles d'exemple (selon votre cas) vers la racine :

   Option A : Votre proxy est installé sur la machine hôte (le plus simple)

   cp examples/docker-compose.override.yml.example docker-compose.override.yml
   

   Option B : Votre proxy tourne lui-même dans un conteneur Docker

   cp examples/docker-compose.override.proxy-container.yml.example docker-compose.override.yml
   

3. Dans votre fichier .env, définissez également TRUST_PROXY=127.0.0.1 (ou l'IP de votre proxy).

4. Configurez votre proxy externe pour rediriger les requêtes vers :

   • 127.0.0.1:13000 (Backend : API, ActivityPub, Uploads)
   • 127.0.0.1:18080 (Frontend)

Attention (Docker) : Si votre reverse proxy tourne lui-même dans un conteneur Docker, 127.0.0.1 ne fonctionnera pas (il pointera vers le conteneur du proxy). Vous devrez connecter les conteneurs Fediclé au réseau de votre proxy et utiliser les noms de services fedicle-engine:13000 et fedicle-portal:80. Voir les exemples avancés dans le dossier examples/.

Des exemples de configuration pour Nginx et Caddy sont disponibles dans le dossier examples/reverse-proxy/.

Note : Cette méthode utilise un fichier override ignoré par Git, ce qui garantit que vos personnalisations ne bloqueront pas les futures mises à jour du projet.

2. Mises à jour (Gérer les versions)

Fediclé évolue via des versions taguées. Ne faites pas de mises à jour "à l'aveugle" avec un simple git pull.

Pour mettre à jour votre instance :

1. Récupérer les nouvelles versions disponibles :

   git fetch --tags
   

2. Voir la liste des versions (facultatif) :

   git tag -l
   # Affiche par exemple : v0.1.7-alpha, v0.2.0-alpha...
   

3. Basculer sur la version souhaitée (ex: v0.4.15-alpha) :

   git checkout tags/v0.4.18-alpha
   

   Cela place votre code dans l'état exact de cette version.

4. Appliquer la mise à jour :

   # Note : --no-cache est fortement recommandé pour garantir l'application des changements de dépendances
   docker compose build --no-cache && docker compose up -d --remove-orphans --force-recreate
   

---

🛡️ Précautions de Survie (Anti-destruction)

À LIRE ABSOLUMENT POUR NE PAS PERDRE VOS DONNÉES.

Voir SECURITY.md pour les détails complets des mesures de sécurité.

1. Le fichier .env est SACRÉ 💀

Ce fichier contient la variable ENCRYPTION_SECRET.

• Cette clé sert à chiffrer les données sensibles (notamment la clé privée ActivityPub générée par le serveur pour chaque compte) dans la base de données. Elle est distincte de votre clé privée OpenPGP personnelle.
• Si vous perdez ce fichier ou modifiez cette clé, toutes vos données cryptées deviennent illisibles à jamais.
• Même si vous avez une sauvegarde de la base de données, sans ce fichier, elle est inutilisable.
• CONSEIL : Copiez le contenu de votre .env en lieu sûr (gestionnaire de mots de passe, clé USB chiffrée, etc.).

2. Comprendre les commandes Docker (et leurs paramètres) 💣

Voici les commandes essentielles pour gérer votre instance et pourquoi nous utilisons certains drapeaux spécifiques :

• docker compose up -d --remove-orphans (Mise à jour / Démarrage standard)

  • up -d : Lance les conteneurs en arrière-plan.
  • --remove-orphans : Indispensable lors des mises à jour. Si la nouvelle version de Fediclé supprime ou renomme un service (ex: un vieux conteneur de maintenance), ce drapeau nettoie automatiquement ces conteneurs fantômes. Sans lui, ils continuent de tourner, consommant des ressources et risquant de provoquer des conflits d'IP ou de ports.

• docker compose up -d --force-recreate (Réparation / Forçage)

  • À utiliser en cas de problème. Si vous modifiez le fichier .env et que les changements ne semblent pas pris en compte, ou si un service bug.
  • Ce drapeau force Docker à détruire et recréer les conteneurs à neuf (sans toucher à la base de données), garantissant que toute la configuration est rechargée proprement.

• docker compose stop : Arrête les conteneurs proprement.

• docker compose restart : Redémarrage simple.

⛔ COMMANDE INTERDITE : Ne lancez JAMAIS docker compose down -v (avec l'option -v). Cela demande à Docker de supprimer les volumes, c'est-à-dire d'effacer définitivement votre base de données.

3. En cas de problème après une mise à jour

Si la nouvelle version ne fonctionne pas, vous pouvez revenir en arrière très simplement :

# 1. Revenir à la version précédente (ex: v0.4.3-alpha)
git checkout tags/v0.4.3-alpha

# 2. Relancer les conteneurs
docker compose build && docker compose up -d --remove-orphans --force-recreate

---

🆘 Dépannage (Troubleshooting)

1. Les changements dans le .env ne sont pas pris en compte

Docker Compose met parfois en cache la configuration. Si vous modifiez votre .env et que rien ne change :

# Force la recréation des conteneurs avec la nouvelle configuration
docker compose up -d --force-recreate

2. Le serveur affiche une erreur 502 (Bad Gateway)

Cela signifie que le moteur (engine) a planté ou n'a pas pu démarrer. La cause est souvent une mauvaise connexion à la base de données. Vérifiez les journaux :

docker logs fedicle-engine

Si vous voyez Authentication failed against database server, vérifiez vos identifiants dans le .env.

3. Nettoyage complet (En cas de comportement bizarre)

Si l'application semble "hantée" par d'anciens réglages ou des conteneurs fantômes :

# Arrête tout et supprime les conteneurs orphelins (sans toucher aux données)
docker compose down --remove-orphans

# Relance avec reconstruction forcée sans cache (recommandé pour les changements de stack)
docker compose up -d --build --no-cache --force-recreate

4. Conflits de variables d'environnement

Fediclé utilise désormais le préfixe FEDICLE_DB_* pour ses variables internes afin d'éviter les conflits avec les variables système (PGUSER, etc.). Assurez-vous que votre fichier .env est à jour par rapport au .env.example.

5. Avertissement Redis "Memory overcommit must be enabled!"

Si vous voyez ce message dans les logs de Redis :

# WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail under low memory condition.

Ce n'est pas bloquant, mais il est recommandé de l'activer pour éviter des problèmes en cas de mémoire faible. Sur votre serveur hôte, exécutez :

# Activation temporaire (valable jusqu'au prochain redémarrage)
sudo sysctl -w vm.overcommit_memory=1

# Activation permanente
echo 'vm.overcommit_memory = 1' | sudo tee -a /etc/sysctl.conf

---

💾 Sauvegardes et Restauration

Les 3 éléments vitaux à sauvegarder

1. Le fichier .env : Contient ENCRYPTION_SECRET (déchiffrement des données) et les accès DB.
2. La Base de données : L'intégralité du contenu (utilisateurs, posts, signatures).
3. Les Médias : Dossier uploads (avatars, en-têtes et images jointes).

---

1. Procédure de Sauvegarde (Backup)

Cette procédure doit être effectuée pendant que l'instance est en cours d'exécution.

# A. Extraire les données de la base de données
# On crée un dump SQL complet
docker exec fedicle-vault pg_dumpall -c -U postgres > dump.sql

# B. Archiver le volume des médias (Uploads)
# On utilise un conteneur temporaire pour accéder au volume nommé
docker run --rm -v engine-uploads:/data -v $(pwd):/backup alpine tar czf /backup/uploads.tar.gz -C /data .

# C. Créer l'archive finale datée
# On regroupe le .env, le dump et les médias
tar -czvf backup_fedicle_$(date +%F).tar.gz .env dump.sql uploads.tar.gz

# D. Nettoyage
rm dump.sql uploads.tar.gz

---

2. Procédure de Restauration

À utiliser pour migrer vers un nouveau serveur ou après une perte totale.

Étape A : Préparation de l'environnement

# 1. Récupérer le code source
git clone https://forgejo.votre-instance.tld/fedicle/fedicle.git
cd fedicle

# 2. Extraire votre archive de sauvegarde ici
tar -xzvf backup_fedicle_XXXX-XX-XX.tar.gz
# (Ceci restaure votre fichier .env, dump.sql et uploads.tar.gz)

Étape B : Restauration des volumes et données

# 1. Restaurer les fichiers médias dans le volume Docker
docker run --rm -v engine-uploads:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/uploads.tar.gz"

# 2. Lancer UNIQUEMENT la base de données
# Le .env étant présent, Docker l'utilisera pour configurer Vault
docker compose up -d vault

# 3. Attendre que la base soit prête (environ 10-15 secondes)
# Puis injecter le dump SQL
cat dump.sql | docker exec -i fedicle-vault psql -U postgres

Étape C : Finalisation

# Lancer le reste des services
docker compose up -d --remove-orphans

# Nettoyage du dump et de l'archive média (optionnel)
rm dump.sql uploads.tar.gz

---

🔍 Outils de Diagnostic (Santé de l'instance)

Fediclé inclut des outils pour vérifier que votre serveur est bien configuré et "voit" correctement le Fédivers.

1. Diagnostic de Fédération (ActivityPub)

Cette commande teste WebFinger, le profil Actor, les collections et la capacité à recevoir des activités.

docker exec -it fedicle-engine node dist/scripts/test_federation.js votre_nom_utilisateur

2. Vérification du flux de signature (OpenPGP)

Vérifie que le moteur de signature et le stockage des clés fonctionnent localement.

docker exec -it fedicle-engine node dist/scripts/verify_flow.js

3. Consultation des Logs

En cas de comportement bizarre, les logs sont vos meilleurs amis :

# Voir les logs du moteur (API / Inbox)
docker logs -f fedicle-engine

# Voir les logs du worker (Livraison ActivityPub)
docker logs -f fedicle-worker

# Voir les logs de la base de données
docker logs -f fedicle-vault

---

🤖 Automatisation (Pour aller plus loin)

Sauvegarde automatique (Cron)

Vous pouvez automatiser la sauvegarde chaque nuit à 3h00 du matin. Créez un script backup.sh à la racine :

#!/bin/bash
# Aller dans le dossier fedicle (Adaptez le chemin !)
cd /home/utilisateur/fedicle

# Créer le dossier backups s'il n'existe pas
mkdir -p backups

# Exécuter la sauvegarde
docker exec fedicle-vault pg_dumpall -c -U postgres > dump.sql
docker run --rm -v engine-uploads:/data -v $(pwd):/backup alpine tar czf /backup/uploads.tar.gz -C /data .
tar -czvf backups/backup_$(date +%F).tar.gz .env dump.sql uploads.tar.gz

# Nettoyage
rm dump.sql uploads.tar.gz

# Optionnel : Supprimer les sauvegardes de plus de 30 jours
find backups/ -name "backup_*.tar.gz" -mtime +30 -delete

Ajoutez-le à votre crontab (crontab -e) : 0 3 * * * /bin/bash /home/utilisateur/fedicle/backup.sh

Note : Assurez-vous que l'utilisateur exécutant le cron a les droits d'exécuter Docker.

Gestion de la taille des logs

Par défaut, Docker peut générer de gros fichiers de logs. Pour limiter leur taille, vous pouvez ajouter ceci à votre docker-compose.yml pour chaque service :

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

---

🛠️ Guide de Développement (Contributeurs)

Cette section est réservée aux développeurs souhaitant modifier le code source de Fediclé.

Stack Technique

• Runtime : Node.js v24.14.0+ & pnpm v10+
• Backend : Fastify, Prisma, TypeScript
• Frontend : React 19, Vite 8, TailwindCSS 4

Voir ARCHITECTURE.md pour plus de détails sur l'architecture.

Environnement Local

1. Installer les dépendances :

   pnpm install
   

2. Configuration : Copiez .env.example en .env et assurez-vous que DATABASE_URL est correct pour votre base de données locale. Définissez NODE_ENV=development.

3. Lancer la base de données (si pas de Postgres local) :

   docker compose up -d vault
   

4. Synchroniser la base de données :

   # Pour le développement initial ou rapide :
   pnpm run --filter "@fedicle/server" db:push
   # POUR TOUTE MODIFICATION DE SCHÉMA (Recommandé) :
   # Voir [MIGRATION.md](./MIGRATION.md) pour utiliser 'prisma migrate dev'
   

5. Démarrer en mode Watch :

   pnpm run dev
   

Tests

• pnpm test : Lance tous les tests unitaires.
• pnpm test:docker : Lance les tests d'intégration contre PostgreSQL dans Docker (Base fedicle_test).

Voir TESTS.md pour plus de détails sur l'infrastructure de tests.

Maintenance et Sauvegarde

Sauvegarder la base de données

docker exec fedicle-vault pg_dump -U fedicle fedicle > backup.sql

Restaurer une sauvegarde

cat backup.sql | docker exec -i fedicle-vault psql -U fedicle fedicle

Promouvoir un administrateur

pnpm run --filter "@fedicle/server" promote-admin user@domaine.tld

• pnpm run build : Compile le projet (TypeScript).
• pnpm i18n:extract : Met à jour les fichiers de traduction.

---

📄 Licence

Ce projet est distribué sous licence AGPL-3.0. Voir le fichier LICENSE pour plus de détails.