lionel/202601docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation complète: infrastructure, réseau, issues, recommandations

Browse Source
This commit is contained in:
Lionel
2025-12-31 20:38:04 +01:00
parent 891d5f1a7d
commit cf5669b1fa
8 changed files with 641 additions and 802 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
docs/infra/issues-2025-12-31.md Normal file
View File

@@ -0,0 +1,145 @@
# Problèmes rencontrés - 31 décembre 2025
Session de maintenance majeure pour réparer l'infrastructure après réorganisation.
## 1. Shlink - URLs cassées
**Symptôme** : Les short URLs (`go/ts`, `go/ui`, etc.) ne fonctionnaient plus.
**Cause** : Le Caddyfile contenait des redirections manuelles au lieu d'un reverse proxy vers Shlink.
**Solution** :
```caddyfile
# AVANT (cassé)
go.talloires.local {
redir /ts https://tailscale.com permanent
redir /ui https://unifi.ui.com permanent
}
# APRÈS (fonctionnel)
go.talloires.local {
reverse_proxy shlink:8080
}
```
**Fichiers modifiés** :
- `/mnt/mediaserver/talloires/caddy/Caddyfile`
- `/home/lionel/talloires-v2/shlink-web/servers.json`
---
## 2. Arcane - Crash loop
**Symptôme** : Container en restart permanent.
**Cause** : `ENCRYPTION_KEY` invalide (31 caractères au lieu de 32+).
**Solution** :
```bash
# Générer nouvelles clés
openssl rand -base64 32
# Mettre à jour docker-compose.yml
ENCRYPTION_KEY=fY+ln5hq7XMkDR+cU/pxu3Kf11LgUkjYXdM+QSwU3jM=
SESSION_SECRET=QDGWo1nA9Qa4fRT2ektsjQ0oUbuAwUz4V8xsBfZYiWw=
```
**Note** : Authelia désactivé temporairement pour Arcane.
---
## 3. Jellyfin - Médias non montés
**Symptôme** : Bibliothèques vides, médias inaccessibles.
**Cause** : Volumes Docker pointaient vers `/mnt/annecy` au lieu de `/mnt/mediaserver`.
**Solution** : Correction des bind mounts dans `docker-compose.yml`.
---
## 4. Gitea + Authelia - OIDC cassé
**Symptôme** : `500 Internal Server Error` lors du login Authelia.
**Cause** : Gitea ne faisait pas confiance au certificat SSL de Caddy (nouveau CA après régénération).
**Solution** :
```bash
# Copier le CA dans Gitea
docker exec caddy cat /data/caddy/pki/authorities/local/root.crt > /tmp/caddy-root.crt
docker cp /tmp/caddy-root.crt gitea:/usr/local/share/ca-certificates/
docker exec gitea update-ca-certificates
docker restart gitea
```
---
## 5. Authelia - Base de données read-only
**Symptôme** : `Could not save the consent session`
**Cause** : Le dossier `/home/lionel/docker/authelia/config/` avait été supprimé lors du nettoyage, mais le container montait encore ce chemin.
**Solution** :
```bash
# Restaurer depuis l'archive
tar xzf /mnt/mediaserver/backups/docker-v1-archive-20251231.tar.gz \
-C /home/lionel docker/authelia
docker restart authelia
```
---
## 6. Home Assistant - Onboarding inattendu
**Symptôme** : Page de création de compte au lieu du login.
**Cause** : Le container montait `/mnt/mediaserver/talloires/homeassistant` mais la config restaurée était dans `/home/lionel/talloires-v2/homeassistant`.
**Solution** :
```bash
# Copier la config restaurée vers le bon emplacement
cp -a /home/lionel/talloires-v2/homeassistant /mnt/mediaserver/talloires/homeassistant
docker restart homeassistant
```
---
## 7. Transmission - HTTP 502
**Symptôme** : Bad Gateway lors de l'accès.
**Cause** : Caddy cherchait `transmission:9091` mais Transmission utilise `network_mode: service:wireguard`.
**Solution** :
```caddyfile
# Dans Caddyfile
reverse_proxy wireguard:9091 # Pas transmission:9091
```
---
## 8. Dozzle - Non accessible
**Symptôme** : URL ne fonctionnait pas.
**Cause** : Dozzle n'était pas configuré dans le Caddyfile.
**Solution** :
```caddyfile
dozzle.talloires.local, dozzle.talloires.tailfd281f.ts.net {
import authelia
reverse_proxy dozzle:8080
import internal_tls
}
```
---
## Leçons apprises
1. **Toujours vérifier les points de montage** avant de supprimer des dossiers
2. **Les certificats CA** doivent être installés dans chaque container qui fait des requêtes HTTPS internes
3. **Documenter les chemins réels** utilisés par chaque service
4. **Garder une archive** avant toute réorganisation majeure

114
docs/infra/network.md Normal file
View File

@@ -0,0 +1,114 @@
# Réseau & Accès
## Tailscale VPN
Tailscale remplace ZeroTier depuis décembre 2025 pour le mesh VPN.
### Configuration
| Machine | IP Tailscale | Hostname |
|---------|--------------|----------|
| Talloires (RPi5) | 10.171.171.1 | talloires.tailfd281f.ts.net |
| Annecy (Synology) | 10.171.171.50 | annecy.tailfd281f.ts.net |
| Mac Lionel | 100.x.x.x | (dynamique) |
### DNS MagicDNS
Tailscale fournit la résolution DNS automatique :
```
*.talloires.tailfd281f.ts.net → Services Talloires
```
### Accès aux services
Tous les services sont accessibles via deux domaines :
| Type | Domaine | Exemple |
|------|---------|---------|
| LAN | `*.talloires.local` | `jellyfin.talloires.local` |
| Tailscale | `*.talloires.tailfd281f.ts.net` | `jellyfin.talloires.tailfd281f.ts.net` |
## Accès LAN
### Prérequis
1. **Certificat CA Caddy** installé sur le client
2. **DNS local** configuré (dnsmasq ou /etc/hosts)
### Installation du certificat
```bash
# Sur Talloires
docker exec caddy cat /data/caddy/pki/authorities/local/root.crt > caddy-root.crt
# Sur Mac
sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain caddy-root.crt
```
### Configuration DNS
Option 1 : **dnsmasq** sur le routeur
```
address=/talloires.local/192.168.1.100
```
Option 2 : **/etc/hosts** sur chaque client
```
192.168.1.100 jellyfin.talloires.local
192.168.1.100 git.talloires.local
192.168.1.100 homeassistant.talloires.local
# etc.
```
## Ports exposés
| Port | Service | Protocole |
|------|---------|-----------|
| 443 | Caddy (HTTPS) | TCP |
| 80 | Caddy (HTTP → HTTPS) | TCP |
| 2222 | Gitea SSH | TCP |
| 8123 | Home Assistant (interne) | TCP |
## Sécurité
### Authelia SSO
La plupart des services sont protégés par Authelia :
```
Client → Caddy → Authelia → Service
```
Services protégés par Authelia :
- Transmission
- Netdata
- Dozzle
- Cockpit
Services avec auth propre (bypass Authelia) :
- Jellyfin (auth interne)
- Gitea (OIDC via Authelia)
- Home Assistant (auth interne)
- Arcane (désactivé temporairement)
### ProtonVPN (WireGuard)
Transmission utilise un tunnel WireGuard vers ProtonVPN :
```
Transmission → WireGuard container → ProtonVPN → Internet
↓
Kill switch intégré
(network_mode: service:wireguard)
```
Vérification IP :
```bash
# IP Transmission (doit être ProtonVPN)
docker exec transmission curl -s ifconfig.me
# IP locale
curl -s ifconfig.me
```

432
docs/infra/overview.md
View File

@@ -1,382 +1,94 @@
# Infrastructure Talloires v2.0
# Infrastructure Overview
Documentation de l'infrastructure réseau, VPN, DNS, et backups.
## Hardware
---
### Talloires (Raspberry Pi 5 - 8GB)
## 🖥️ Serveurs
| Composant | Détails |
|-----------|---------|
| CPU | Broadcom BCM2712 (4x Cortex-A76 @ 2.4GHz) |
| RAM | 8 GB LPDDR4X |
| Stockage | SD Card 64GB + SSD 4TB USB |
| Réseau | Ethernet 1Gbps |
| OS | Raspberry Pi OS (Debian 12 Bookworm) |
### Talloires (Production)
- **Type**: Raspberry Pi 5 (8GB RAM)
- **OS**: Raspberry Pi OS (Debian 12)
- **IP Tailscale**: `100.116.198.105`
- **Hostname**: `talloires.tailfd281f.ts.net`
- **Rôle**: Serveur principal (Docker)
### Annecy (Synology DS620slim)
### Annecy (Storage)
- **Type**: Synology DS620slim
- **OS**: DSM 7.x
- **IP Tailscale**: `100.69.227.96`
- **Hostname**: `annecy.tailfd281f.ts.net`
- **Rôle**: NAS, Backups
| Composant | Détails |
|-----------|---------|
| Stockage | 6x SSD en RAID |
| Rôle | NAS backup, stockage long terme |
| Accès | NFS via Tailscale |
### Theseus (Network)
- **Type**: UniFi Dream Router 7
- **Rôle**: Gateway, Firewall, DHCP
### Theseus (UniFi Dream Router 7)
---
| Rôle | Détails |
|------|---------|
| Routeur | Gateway réseau domestique |
| WiFi | WiFi 7 (BE) |
| DHCP | 192.168.1.0/24 |
## 🐳 Outils Docker Management
## Points de montage
### 🎨 Arcane - Web UI
**URL**: [go/arcane](https://go/arcane)
**License**: BSD-3-Clause
**Status**: ✅ Opérationnel
**Fonctionnalités:**
- Gestion containers, images, volumes, networks
- Docker Compose templates & projects
- Monitoring temps réel (CPU/RAM)
- Interface moderne & responsive
- Multi-serveurs (via agents)
**Usage:**
```bash
# Accès web
https://go/arcane
# SD Card (OS + configs)
/dev/mmcblk0p2 → / # 58 GB
# Credentials par défaut
Username: arcane
Password: arcane-admin
# SSD externe (données)
/dev/sda1 → /mnt/mediaserver # 4 TB
# NFS Synology (backups)
10.171.171.50:/volume1/Backups → /mnt/annecy
```
**Alternative à:** Portainer (proprietary), Dockge (unstable)
## Structure des fichiers
---
```
/home/lionel/
└── talloires-v2/ # Configurations Docker
├── infra/ # Caddy, Authelia
├── media/ # Jellyfin compose
├── monitoring/ # Netdata, Dozzle
├── tools/ # Shlink, Gitea compose
├── docker-mgmt/ # Arcane
├── automation/ # Home Assistant
├── transmission/ # Transmission + WireGuard
├── mkdocs/ # Cette documentation
├── jellyfin/ # Config Jellyfin (3.6GB)
├── homeassistant/ # Config HA (dupliqué sur SSD)
└── arcane/ # Config Arcane
### 📋 Dozzle - Logs Viewer
/mnt/mediaserver/
├── talloires/ # Données services
│ ├── caddy/ # Caddyfile + certs
│ ├── gitea/ # Repos git + DB
│ ├── homeassistant/ # Config active HA
│ └── authelia/ # (si présent)
├── jellyfin-cache/ # Cache Jellyfin
├── netdata-cache/ # Cache Netdata
├── movies/ # Bibliothèque films
├── series/ # Bibliothèque séries
├── musicvideos/ # Clips musicaux
├── lionel/ # Médias Lionel
├── fiona/ # Médias Fiona
└── backups/ # Archives
```
**URL**: [go/logs](https://go/logs)
**License**: MIT
**Status**: ✅ Opérationnel
## Réseaux Docker
**Fonctionnalités:**
- Real-time log streaming
- Multi-container view
- Search & filter
- Ultra-léger (~30 MB RAM)
- Aucune base de données
**Usage:**
```bash
# Accès web
https://go/logs
# Réseau principal pour tous les services
talloires_net (172.18.0.0/16)
# Pas d'authentification requise (Tailscale VPN only)
# Services connectés :
- caddy, authelia, gitea, jellyfin, homeassistant
- mkdocs, shlink, shlink-web, arcane, dozzle
- netdata, signal-api, transmission, wireguard
```
**Use cases:** Debug, troubleshooting, monitoring logs
## Adresses IP
---
### ⚡ Lazydocker - Terminal UI
**License**: MIT
**Status**: ✅ Installé sur Talloires & Annecy
**Version**: 0.24.3
**Installation:**
```bash
# Talloires
lazydocker --version
# Location: /usr/local/bin/lazydocker
# Annecy (Synology)
~/.local/bin/lazydocker --version
```
**Fonctionnalités:**
- TUI (Terminal User Interface)
- Stats en temps réel (CPU/RAM)
- Logs interactifs
- Actions rapides (start/stop/restart)
- Fonctionne via SSH
**Usage:**
```bash
# Sur Talloires
ssh lionel@talloires.local
lazydocker
# Sur Annecy
ssh lionel@100.69.227.96
~/.local/bin/lazydocker
```
**Navigation:**
- `↑/↓`: Sélection
- `Enter`: Actions
- `l`: Logs
- `e`: Exec shell
- `q`: Quitter
---
### 📊 Comparaison Outils
| Feature | Arcane | Dozzle | Lazydocker |
|---------|--------|--------|------------|
| **Type** | Web UI | Web UI | TUI |
| **Containers** | ✅ Full mgmt | ❌ View only | ✅ Full mgmt |
| **Logs** | ✅ | ✅ | ✅ |
| **Compose** | ✅ Templates | ❌ | ✅ View |
| **Stats** | ✅ | ❌ | ✅ |
| **Remote** | ✅ Multi-host | ❌ Single | ❌ Single |
| **SSH** | ❌ | ❌ | ✅ Works |
| **RAM** | ~100 MB | ~30 MB | ~50 MB |
**Recommandations:**
- **Arcane**: Gestion quotidienne, templates, multi-serveurs
- **Dozzle**: Quick log inspection, debugging
- **Lazydocker**: SSH access, TUI lovers, remote management
---
## 🌐 Réseau
### Tailscale VPN
- **Type**: WireGuard mesh VPN
- **MagicDNS**: Désactivé (dnsmasq preferred)
- **Subnet**: `100.64.0.0/10`
### DNS Local (dnsmasq)
**Config**: `/etc/dnsmasq.d/tailscale.conf`
```
# Machines
address=/talloires.local/100.116.198.105
address=/annecy.local/100.69.227.96
# Wildcards
address=/.talloires.local/100.116.198.105
# Go-links
address=/go/100.116.198.105
# Upstream DNS
server=127.0.0.1#5053
```
### AdGuard DNS (DoH)
- **Port**: 5053
- **Upstream**: AdGuard DNS-over-HTTPS
- **Config**: `cloudflared` tunnel
---
## 🔐 VPN Tunnel (ProtonVPN)
### Configuration WireGuard
- **Server**: Luxembourg (LU#44)
- **Public IP**: 5.253.204.190
- **Endpoint**: 5.253.204.162:51820
- **Config**: `/home/lionel/talloires-v2/transmission/wireguard/wg0.conf`
### Kill-Switch
Transmission utilise `network_mode: service:wireguard` → Impossible de leak l'IP réelle.
### Monitoring VPN
- Vérification automatique IP publique
- Alertes Telegram si VPN down (<30s)
- Health checks Docker
---
## 💾 Backups
### Structure NFS
```
/mnt/annecy/talloires/
├── migration-v2/ # Backups migration
│ ├── jellyfin-config-*.tar.gz # 2.3 GB
│ ├── gitea-data-*.tar.gz # Repos Git
│ ├── mkdocs-v1-archive-*.tar.gz # 12 KB
│ └── critical-configs-*.tar.gz # 3.5 KB
└── daily/ # Backups quotidiens (TODO)
```
### NFS Mount
```bash
sudo mount -t nfs 100.69.227.96:/volume1/talloires /mnt/annecy -o rw,hard,intr,rsize=8192,wsize=8192
```
**Fstab**:
```
100.69.227.96:/volume1/talloires /mnt/annecy nfs rw,hard,intr,rsize=8192,wsize=8192 0 0
```
### Backup Automatique (Cron)
TODO: Mettre à jour cron pour v2.0 structure.
---
## 🔒 Sécurité
### Firewall (UFW)
```bash
sudo ufw status
```
Ports ouverts:
- 80, 443: HTTP/HTTPS (Caddy)
- 2222: SSH Gitea
- 8096: Jellyfin (direct access)
- 22: SSH (Tailscale only)
### Certificats HTTPS
- **CA**: Caddy Local Authority
- **Cert**: `/data/caddy/pki/authorities/local/root.crt`
- **Installation**: Importer dans macOS Keychain → Always Trust
### Accès
- Tailscale VPN uniquement
- Pas d'exposition Internet directe
- SSH keys only (no password)
---
## 📊 Monitoring
### Stack Monitoring
**Netdata** - System metrics
- **URL**: `https://go/net`
- **Métriques**: CPU, RAM, Disk, Network, Docker
- **Alertes**: À configurer (optionnel)
**Arcane** - Docker monitoring
- **URL**: `https://go/arcane`
- **Métriques**: Containers stats (CPU/RAM)
- **Features**: Dashboard, projects, logs
**Dozzle** - Logs viewer
- **URL**: `https://go/logs`
- **Features**: Real-time logs, search, filter
**Lazydocker** - Terminal monitoring
```bash
ssh lionel@talloires.local
lazydocker
```
### Docker Health Checks
Tous les containers ont des health checks configurés.
### Logs
```bash
# CLI
docker logs <container>
docker logs <container> --follow
docker logs <container> --tail 100
# Web UI (Dozzle)
https://go/logs
# TUI (Lazydocker)
lazydocker
```
---
## 🛠️ Maintenance
### Docker Management
**Via Arcane (Web):**
```
https://go/arcane
→ Containers → Start/Stop/Restart
→ Images → Pull/Delete
→ Projects → Manage Compose stacks
```
**Via Lazydocker (TUI):**
```bash
ssh lionel@talloires.local
lazydocker
# Navigate avec arrows, Enter pour actions
```
**Via CLI:**
```bash
# Update containers
cd /home/lionel/talloires-v2/core
docker compose pull
docker compose up -d
# Restart service
docker restart <container>
# View logs
docker logs <container> --tail 100
```
### Backup Manuel
```bash
# Jellyfin
tar -czf /mnt/annecy/talloires/manual/jellyfin-$(date +%Y%m%d).tar.gz \\
/home/lionel/talloires-v2/jellyfin/config
# Gitea
tar -czf /mnt/annecy/talloires/manual/gitea-$(date +%Y%m%d).tar.gz \\
/home/lionel/talloires-v2/gitea/
# Arcane database
tar -czf /mnt/annecy/talloires/manual/arcane-$(date +%Y%m%d).tar.gz \\
/home/lionel/talloires-v2/docker-mgmt/arcane-data
```
### Restart Services
```bash
docker restart <container>
docker compose restart
```
---
## 📁 Fichiers de Configuration
### Docker Management
```
/home/lionel/talloires-v2/docker-mgmt/
├── docker-compose.yml # Arcane + Dozzle
└── arcane-data/ # Arcane database
```
### Caddy
```
/home/lionel/talloires-v2/caddy/
├── Caddyfile # Reverse proxy config
└── Caddyfile.backup-* # Backups automatiques
```
### Services
```
/home/lionel/talloires-v2/
├── core/ # Caddy, Shlink
├── jellyfin/ # Media server
├── transmission/ # BitTorrent + WireGuard
├── gitea/ # Git hosting
├── homeassistant/ # Domotique
├── mkdocs/ # Documentation
├── netdata/ # Monitoring
├── signal-api/ # Notifications
└── docker-mgmt/ # Arcane + Dozzle
```
---
*Voir [Services](../services/overview.md) pour configuration applicative.*
*Dernière mise à jour: 31 décembre 2025*
| Service | IP Locale | Tailscale |
|---------|-----------|-----------|
| Talloires | 192.168.1.100 | 10.171.171.1 |
| Annecy | 192.168.1.50 | 10.171.171.50 |

136
docs/infra/recommendations.md Normal file
View File

@@ -0,0 +1,136 @@
# Recommandations & Next Steps
## Priorité haute 🔴
### 1. Migration SD → SSD 512GB
**Situation actuelle** :
- SD Card 64GB : 69% utilisé (OS + configs)
- SSD 4TB : données uniquement
**Recommandation** : Boot sur SSD 512GB pour :
- Meilleure fiabilité (SD cards = points de défaillance)
- Meilleures performances I/O
- Plus d'espace pour les configs Docker
**Étapes** :
```bash
# 1. Cloner la SD vers le SSD
sudo dd if=/dev/mmcblk0 of=/dev/sdX bs=4M status=progress
# 2. Étendre la partition
sudo raspi-config # Advanced > Expand Filesystem
# 3. Configurer le boot USB
sudo raspi-config # Advanced > Boot Order > USB Boot
# 4. Modifier /boot/cmdline.txt si nécessaire
```
### 2. Migrer Jellyfin config vers SSD
**Situation** : 3.6 GB de config Jellyfin sur SD card
```bash
# Déplacer vers SSD
mv /home/lionel/talloires-v2/jellyfin /mnt/mediaserver/talloires/jellyfin
# Mettre à jour docker-compose.yml
volumes:
- /mnt/mediaserver/talloires/jellyfin:/config
```
### 3. Réactiver Authelia pour Arcane
Actuellement désactivé pour contourner un problème d'accès.
```caddyfile
# Dans Caddyfile, réactiver :
arcane.talloires.local {
import authelia # Décommenter
reverse_proxy arcane:3000
}
```
---
## Priorité moyenne 🟡
### 4. Corriger l'erreur SMTP Home Assistant
```yaml
# configuration.yaml - utiliser un app password ProtonMail
notify:
- platform: smtp
server: 127.0.0.1 # Via ProtonMail Bridge
port: 1025
sender: xxx@protonmail.com
username: xxx
password: !secret smtp_password
```
### 5. Unifier les chemins de configuration
Actuellement dispersés entre :
- `/home/lionel/talloires-v2/` (configs Docker Compose)
- `/mnt/mediaserver/talloires/` (données services)
- `/home/lionel/docker/` (ancien, à migrer)
**Recommandation** : Tout consolider sur le SSD après migration.
### 6. Backup automatisé des configs
```bash
# Ajouter au cron
0 4 * * * tar czf /mnt/annecy/talloires-config-$(date +%Y%m%d).tar.gz \
/home/lionel/talloires-v2 \
/mnt/mediaserver/talloires
```
### 7. Monitoring des backups
Ajouter des alertes si les backups échouent :
- Healthchecks.io pour le cron
- Telegram bot pour alertes critiques
---
## Priorité basse 🟢
### 8. SNMP monitoring Synology
Ajouter le monitoring RAID et disques du NAS Annecy.
### 9. Documentation continue
- Mettre à jour MkDocs après chaque modification
- Sync bidirectionnelle avec Gitea fonctionne ✅
### 10. Nettoyer les anciennes archives
```bash
# Après validation de la migration SSD
rm /mnt/mediaserver/backups/docker-v1-archive-20251231.tar.gz
```
---
## Améliorations futures
### Infrastructure
- [ ] Cluster Raspberry Pi pour haute disponibilité
- [ ] Déploiement distribué chez famille (Paris, Annecy)
- [ ] Cache intelligent multi-sites pour Jellyfin
### Sécurité
- [ ] Audit Lynis régulier (actuellement 63/100)
- [ ] Fail2ban pour les services exposés
- [ ] Rotation automatique des secrets
### Services
- [ ] Upgrade Gitea → dernière version
- [ ] Ajouter Vaultwarden (password manager)
- [ ] Intégration DevonThink si Mac Mini M1