lionel/202512docs
Archived
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit - Talloires documentation

Browse Source
This commit is contained in:
Lionel Dupré
2025-12-19 16:16:17 +01:00
commit 3cdf44528e
9 changed files with 769 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/index.md Normal file
View File

@@ -0,0 +1,68 @@
# Talloires - Home Server
Bienvenue sur le portail de documentation de **Talloires**, le serveur domestique Raspberry Pi 5.
## Services
### 🎬 Média
| Service | URL | Description |
|---------|-----|-------------|
| Jellyfin | [jellyfin.talloires.local](https://jellyfin.talloires.local) | Streaming média |
| Transmission | [transmission.talloires.local](https://transmission.talloires.local) | Client torrent |
### ✅ Productivité
| Service | URL | Description |
|---------|-----|-------------|
| Vikunja | [vikunja.talloires.local](https://vikunja.talloires.local) | Gestion de tâches (Todoist-like) |
| Outline | [outline.talloires.local](https://outline.talloires.local) | Wiki collaboratif |
| Hoarder | [hoarder.talloires.local](https://hoarder.talloires.local) | Bookmarks avec AI |
| Linkwarden | [linkwarden.talloires.local](https://linkwarden.talloires.local) | Bookmarks avancés |
| LanguageTool | [languagetool.talloires.local](https://languagetool.talloires.local) | Correcteur grammatical |
### 🔧 Infrastructure
| Service | URL | Description |
|---------|-----|-------------|
| Portainer | [portainer.talloires.local](https://portainer.talloires.local) | Gestion Docker |
| Dockge | [dockge.talloires.local](https://dockge.talloires.local) | Docker Compose UI |
| Gitea | [git.talloires.local](https://git.talloires.local) | Git self-hosted |
| MkDocs | [docs.talloires.local](https://docs.talloires.local) | Documentation |
### 📊 Monitoring
| Service | URL | Description |
|---------|-----|-------------|
| Grafana | [grafana.talloires.local](https://grafana.talloires.local) | Dashboards |
| Netdata | [netdata.talloires.local](https://netdata.talloires.local) | Monitoring temps réel |
| Uptime Kuma | [uptime.talloires.local](https://uptime.talloires.local) | Status des services |
| Cockpit | [cockpit.talloires.local](https://cockpit.talloires.local) | Admin système |
### 🏠 Domotique
| Service | URL | Description |
|---------|-----|-------------|
| Home Assistant | [homeassistant.talloires.local](https://homeassistant.talloires.local) | Domotique |
### 🔐 Sécurité
| Service | URL | Description |
|---------|-----|-------------|
| Authelia | [auth.talloires.local](https://auth.talloires.local) | SSO / 2FA |
| CrowdSec | - | Protection intrusion |
## Accès ZeroTier (externe)
Services accessibles via ZeroTier (sans Authelia) :
| Service | URL |
|---------|-----|
| Vikunja | [vikunja.talloires.1871.zt](https://vikunja.talloires.1871.zt) |
| Outline | [outline.talloires.1871.zt](https://outline.talloires.1871.zt) |
| Hoarder | [hoarder.talloires.1871.zt](https://hoarder.talloires.1871.zt) |
| Linkwarden | [linkwarden.talloires.1871.zt](https://linkwarden.talloires.1871.zt) |
| LanguageTool | [languagetool.talloires.1871.zt](https://languagetool.talloires.1871.zt) |
## Accès rapide
- [Vue ensemble des services](services/overview.md)
- [Configuration SSO](services/authelia.md)
- [Backup](services/backup.md)
- [Ports utilisés](reference/ports.md)
- [Commandes utiles](reference/commands.md)
- [Scripts de maintenance](reference/scripts.md)

7
docs/javascripts/external-links.js Normal file
View File

@@ -0,0 +1,7 @@
document.addEventListener('DOMContentLoaded', function() {
var links = document.querySelectorAll('a[href^="http"]');
links.forEach(function(link) {
link.setAttribute('target', '_blank');
link.setAttribute('rel', 'noopener noreferrer');
});
});

118
docs/reference/commands.md Normal file
View File

@@ -0,0 +1,118 @@
# Commandes utiles
## Docker
```bash
# Status de tous les containers
docker ps -a
# Logs dun service
docker logs -f <container>
# Redémarrer un service
docker restart <container>
# Recréer un service (après modif compose)
cd ~/docker/talloires && docker compose up -d <service>
# Tout redémarrer
cd ~/docker/talloires && docker compose down && docker compose up -d
# Shell dans un container
docker exec -it <container> sh
```
## Caddy
```bash
# Recharger la config
docker exec caddy caddy reload --config /etc/caddy/Caddyfile
# Voir les logs
docker logs caddy -f
# Tester la config
docker exec caddy caddy validate --config /etc/caddy/Caddyfile
```
## Authelia
```bash
# Logs
docker logs authelia -f
# Générer un hash de mot de passe
docker exec authelia authelia crypto hash generate argon2 --password "motdepasse"
# Générer un hash pour OIDC secret
docker exec authelia authelia crypto hash generate pbkdf2 --password "secret"
```
## Backup
```bash
# Lancer un backup manuel
~/backup-to-annecy.sh
# Voir le log
cat ~/backup.log
# Lister les backups sur Annecy
sudo ssh -i /root/.ssh/id_ed25519 rsync-talloires@10.171.171.50 "ls -lh /volume1/Backups/talloires/"
```
## Système
```bash
# Espace disque
df -h
# Mémoire
free -h
# Température CPU
vcgencmd measure_temp
# Services systemd
sudo systemctl status docker
sudo systemctl status cockpit
# Logs système
journalctl -f
```
## Réseau
```bash
# IP des containers
docker network inspect talloires_net | grep -A2 Name
# Test DNS Docker
docker exec caddy nslookup authelia
# Connecter un container au réseau
docker network connect talloires_net <container>
```
## CrowdSec
```bash
# Status
docker exec crowdsec cscli metrics
# Décisions actives (bans)
docker exec crowdsec cscli decisions list
# Ajouter un ban manuel
docker exec crowdsec cscli decisions add --ip 1.2.3.4 --reason "test"
```
## Certificats
```bash
# Exporter le CA Caddy (pour clients)
docker exec caddy cat /data/caddy/pki/authorities/local/root.crt > caddy-ca.crt
# Installer sur Mac
security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db caddy-ca.crt
```

77
docs/reference/ports.md Normal file
View File

@@ -0,0 +1,77 @@
# Ports utilisés
## Ports exposés (accessibles via réseau)
| Port | Service | Protocol | Notes |
|------|---------|----------|-------|
| 80 | Caddy (redirect HTTPS) | TCP | Redirige vers 443 |
| 443 | Caddy (reverse proxy) | TCP | Point d'entrée principal |
| 8096 | Jellyfin | TCP | Accès direct (optionnel) |
| 3030 | Gitea HTTP | TCP | Mappé depuis 3000 interne |
| 2222 | Gitea SSH | TCP | Mappé depuis 22 interne |
| 8123 | Home Assistant | TCP | Mode host network |
| 9090 | Cockpit | TCP | Admin système |
| 1514 | Syslog-ng | TCP/UDP | Collecte syslog |
| 51413 | Transmission P2P | TCP/UDP | BitTorrent |
## Ports internes Docker (talloires_net)
| Port | Service(s) | Notes |
|------|------------|-------|
| 3000 | Gitea, Grafana, Linkwarden, Hoarder, Outline | Plusieurs services partagent ce port |
| 3001 | Uptime Kuma | |
| 3100 | Loki | Agrégation logs |
| 3456 | Vikunja | |
| 5001 | Dockge | |
| 5432 | PostgreSQL | Linkwarden-db, Outline-db |
| 6379 | Redis | Outline-redis |
| 8000 | MkDocs | |
| 8010 | LanguageTool | |
| 9000 | Portainer | |
| 9091 | Authelia, Transmission Web | |
| 19999 | Netdata | |
## URLs par domaine
### Accès local (.talloires.local) - avec Authelia
| Service | URL | Authentification |
|---------|-----|------------------|
| Homepage | https://talloires.local | Authelia |
| Auth | https://auth.talloires.local | - |
| Git | https://git.talloires.local | OIDC Authelia |
| Jellyfin | https://jellyfin.talloires.local | Authelia |
| Grafana | https://grafana.talloires.local | Header Auth |
| Portainer | https://portainer.talloires.local | Authelia |
| Dockge | https://dockge.talloires.local | Authelia |
| Docs | https://docs.talloires.local | Authelia |
| Vikunja | https://vikunja.talloires.local | Authelia |
| Outline | https://outline.talloires.local | OIDC Authelia |
| Hoarder | https://hoarder.talloires.local | Authelia |
| Linkwarden | https://linkwarden.talloires.local | Authelia |
| LanguageTool | https://languagetool.talloires.local | Authelia |
| Transmission | https://transmission.talloires.local | Authelia |
| Netdata | https://netdata.talloires.local | Authelia |
| Uptime Kuma | https://uptime.talloires.local | Authelia |
| Cockpit | https://cockpit.talloires.local | Authelia |
| Home Assistant | https://homeassistant.talloires.local | Authelia |
### Accès ZeroTier (.talloires.1871.zt) - sans Authelia
Ces URLs sont accessibles depuis l'extérieur via le réseau ZeroTier, sans passer par Authelia (authentification propre à chaque service).
| Service | URL | Auth native |
|---------|-----|-------------|
| Vikunja | https://vikunja.talloires.1871.zt | Vikunja login |
| Outline | https://outline.talloires.1871.zt | OIDC Authelia |
| Hoarder | https://hoarder.talloires.1871.zt | Hoarder login |
| Linkwarden | https://linkwarden.1871.zt | Linkwarden login |
| LanguageTool | https://languagetool.talloires.1871.zt | Aucune (API) |
## Réseau ZeroTier
| Serveur | IP ZeroTier | Rôle |
|---------|-------------|------|
| Talloires | 10.144.221.22 | Serveur principal (Pi5) |
| Annecy | 10.144.78.193 | NAS Synology (backup) |
| Olympou | 10.144.46.46 | Mac de travail |

56
docs/reference/scripts.md Normal file
View File

@@ -0,0 +1,56 @@
# Scripts de maintenance
Scripts utilitaires pour la gestion de Talloires.
## update-containers.sh
Met à jour tous les containers Docker en parcourant les répertoires avec un fichier docker-compose.
**Emplacement** :
=== Pulling latest images ===
**Usage** :
---
## transmission-toggle.sh
Active/désactive le container Transmission à la demande (économie de ressources).
**Emplacement** :
🔴 Transmission is STOPPED
**Usage** :
---
## backup-to-annecy.sh
Sauvegarde les configs Docker vers le NAS Synology (Annecy).
**Emplacement** :
**Planification** : Cron à 3h00 quotidien
**Vérifier les backups** :
---
## Watchtower (automatique)
Watchtower vérifie et met à jour automatiquement les containers à 4h00.
**Configuration** : Dans
**Logs** :

182
docs/services/authelia.md Normal file
View File

@@ -0,0 +1,182 @@
# Authelia - SSO
Authelia fournit l'authentification unique (SSO) pour tous les services Talloires.
## Accès
| Paramètre | Valeur |
|-----------|--------|
| URL | [auth.talloires.local](https://auth.talloires.local) |
| Utilisateur | lionel |
| Email | dflected@dflected.org |
| 2FA | TOTP activé |
## Services protégés (forward_auth)
Ces services requièrent une authentification via Authelia avant d'accéder au backend :
| Service | URL |
|---------|-----|
| docs | docs.talloires.local |
| portainer | portainer.talloires.local |
| dockge | dockge.talloires.local |
| transmission | transmission.talloires.local |
| netdata | netdata.talloires.local |
| homeassistant | homeassistant.talloires.local |
| uptime | uptime.talloires.local |
| cockpit | cockpit.talloires.local |
| vikunja | vikunja.talloires.local |
| hoarder | hoarder.talloires.local |
| linkwarden | linkwarden.talloires.local |
| languagetool | languagetool.talloires.local |
| jellyfin | jellyfin.talloires.local |
## Services avec OAuth/OIDC
Ces services utilisent Authelia comme provider OpenID Connect :
### Gitea
| Paramètre | Valeur |
|-----------|--------|
| Client ID | gitea |
| Redirect URI | https://git.talloires.local/user/oauth2/Authelia/callback |
| Scopes | openid, email, profile |
### Outline
| Paramètre | Valeur |
|-----------|--------|
| Client ID | outline |
| Redirect URI | https://outline.talloires.local/auth/oidc.callback |
| Scopes | openid, offline_access, profile, email |
### Grafana (Header Auth)
Grafana utilise l'authentification par header via Authelia (pas OIDC) :
| Header | Valeur |
|--------|--------|
| Remote-User | Utilisateur authentifié |
| Remote-Email | Email de l'utilisateur |
## Configuration
### Fichiers
| Fichier | Usage |
|---------|-------|
| ~/docker/authelia/config/configuration.yml | Config principale |
| ~/docker/authelia/config/users_database.yml | Base utilisateurs |
| ~/docker/authelia/config/oidc.key | Clé privée OIDC |
### SMTP (Proton Mail)
| Paramètre | Valeur |
|-----------|--------|
| Serveur | smtp.protonmail.ch:465 |
| Protocol | TLS implicite (submissions://) |
| From | Talloires <dflected@dflected.org> |
### Buffers HTTP
Pour éviter l'erreur 431 (Request Header Fields Too Large), la config inclut :
```yaml
server:
buffers:
read: 8192
write: 8192
```
## Intégration Caddy
### Snippet forward_auth
```
(authelia) {
forward_auth authelia:9091 {
uri /api/authz/forward-auth
copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
}
}
```
### Usage dans Caddyfile
```
monservice.talloires.local {
import authelia
reverse_proxy backend:port
tls internal
}
```
### Bypass Authelia (accès ZeroTier)
```
monservice.talloires.1871.zt {
# Pas de forward_auth = pas d'Authelia
reverse_proxy backend:port
tls internal
}
```
## Ajouter un client OIDC
1. Générer le hash du secret :
```bash
docker exec authelia authelia crypto hash generate pbkdf2 --password "mon-secret"
```
2. Ajouter dans configuration.yml (section identity_providers.oidc.clients) :
```yaml
- client_id: nouveau_client
client_name: Mon Service
client_secret: "$pbkdf2-sha512$..."
public: false
authorization_policy: two_factor
redirect_uris:
- https://service.talloires.local/callback
scopes:
- openid
- email
- profile
token_endpoint_auth_method: client_secret_post
```
3. Redémarrer Authelia :
```bash
docker restart authelia
```
## Commandes utiles
```bash
# Logs
docker logs authelia -f
# Générer un hash de mot de passe utilisateur
docker exec authelia authelia crypto hash generate argon2 --password "motdepasse"
# Générer un hash pour OIDC client secret
docker exec authelia authelia crypto hash generate pbkdf2 --password "secret"
# Valider la configuration
docker exec authelia authelia validate-config
```
## Dépannage
### Erreur 431 (Header Fields Too Large)
Augmenter les buffers dans configuration.yml :
```yaml
server:
buffers:
read: 8192
write: 8192
```
### OIDC "invalid_client"
Vérifier que le client_secret est hashé avec pbkdf2 (pas argon2).
### Cookies non persistants
Vérifier que le domain est correct dans session :
```yaml
session:
cookies:
- domain: talloires.local
authelia_url: https://auth.talloires.local
```

76
docs/services/backup.md Normal file
View File

@@ -0,0 +1,76 @@
# Backup
Sauvegarde automatique de Talloires vers Annecy (Synology NAS).
## Configuration
| Paramètre | Valeur |
|-----------|--------|
| Script | ~/backup-to-annecy.sh |
| Destination | rsync-talloires@10.171.171.50:/volume1/Backups/talloires/ |
| Méthode | tar over SSH (rsync SUID bloqué sur Synology DSM 7) |
| Schedule | Cron quotidien à 3h00 |
| Rétention | 7 derniers backups |
| Log | ~/backup.log |
## Données sauvegardées
- ~/docker/ (toutes les configs Docker)
### Exclusions
- *.log
- */cache/*
- */logs/*
- */__pycache__/*
## Authentification SSH
- Clé privée (root): /root/.ssh/id_ed25519
- Clé privée (lionel): ~/.ssh/id_ed25519
- Utilisateur distant: rsync-talloires
- Fingerprint: SHA256:CxpeBfvrBV/s+RNE49SwrY3WsG28Du3nyQ/2D9lApU8
## Commandes
### Lancer un backup manuel
```bash
~/backup-to-annecy.sh
```
### Vérifier le log
```bash
cat ~/backup.log
```
### Vérifier les backups sur Annecy
```bash
sudo ssh -i /root/.ssh/id_ed25519 rsync-talloires@10.171.171.50 "ls -lh /volume1/Backups/talloires/"
```
### Restaurer un backup
```bash
# Sur Talloires
sudo ssh -i /root/.ssh/id_ed25519 rsync-talloires@10.171.171.50 "cat /volume1/Backups/talloires/docker-backup-YYYYMMDD-HHMMSS.tar.gz" | sudo tar -xzf - -C /home/lionel/
```
## Cron
```bash
# Voir le cron
sudo crontab -l
# Modifier
sudo crontab -e
```
Entrée actuelle :
```
0 3 * * * /home/lionel/backup-to-annecy.sh
```
## Notes techniques
Le rsync classique ne fonctionne pas avec Synology DSM 7 car :
- rsync est SUID root sur DSM
- Les utilisateurs non-admin nont pas de shell par défaut
- Solution: tar over SSH fonctionne parfaitement

149
docs/services/overview.md Normal file
View File

@@ -0,0 +1,149 @@
# Vue ensemble des services
## Architecture
```
Client (Mac/iPhone)
|
| HTTPS (certificat Caddy CA)
v
[Caddy] :443
|
+-- forward_auth --> [Authelia] :9091
| |
| (si authentifié)
| |
+-------------------------+
|
v
Services Docker
```
## Services actifs (24 containers)
### 🎬 Média
| Service | Container | Port | Description |
|---------|-----------|------|-------------|
| Jellyfin | jellyfin | 8096 | Streaming vidéo avec transcodage hardware (VideoCore) |
| Transmission | transmission | 9091, 51413 | Client BitTorrent avec web UI |
### ✅ Productivité
| Service | Container | Port | Description |
|---------|-----------|------|-------------|
| Vikunja | vikunja | 3456 | Gestion de tâches style Todoist/Trello avec CalDAV |
| Outline | outline + outline-db + outline-redis | 3000 | Wiki collaboratif avec OIDC (PostgreSQL + Redis) |
| Hoarder | hoarder | 3000 | Bookmarks intelligents avec tagging AI (Anthropic) |
| Linkwarden | linkwarden + linkwarden-db | 3000 | Gestionnaire de bookmarks avancé avec archivage |
| LanguageTool | languagetool | 8010 | Serveur de correction grammaticale (FR/EN/DE) |
### 🔧 Infrastructure
| Service | Container | Port | Description |
|---------|-----------|------|-------------|
| Portainer | portainer | 9000 | Interface de gestion Docker |
| Dockge | dockge | 5001 | Interface Docker Compose |
| Gitea | gitea | 3000, 22 | Serveur Git avec SSO Authelia |
| MkDocs | mkdocs | 8000 | Cette documentation |
### 📊 Monitoring
| Service | Container | Port | Description |
|---------|-----------|------|-------------|
| Grafana | grafana | 3000 | Dashboards et visualisation (header auth via Authelia) |
| Netdata | netdata | 19999 | Monitoring système temps réel |
| Uptime Kuma | uptime-kuma | 3001 | Surveillance uptime des services |
| Loki | loki | 3100 | Agrégation de logs |
| Promtail | promtail | - | Collecte de logs pour Loki |
| Syslog-ng | syslog-ng | 1514 | Collecte syslog centralisée |
### 🏠 Domotique
| Service | Container | Port | Description |
|---------|-----------|------|-------------|
| Home Assistant | homeassistant | 8123 | Automatisation domotique (mode host network) |
### 🔐 Sécurité
| Service | Container | Port | Description |
|---------|-----------|------|-------------|
| Authelia | authelia | 9091 | SSO, 2FA, OIDC provider |
| CrowdSec | crowdsec | - | IDS/IPS collaboratif |
| Caddy | caddy | 80, 443 | Reverse proxy avec TLS automatique |
### 🔄 Maintenance
| Service | Container | Port | Description |
|---------|-----------|------|-------------|
| Watchtower | watchtower | 8080 | Mise à jour auto des containers (4h00) |
## Répertoires Docker
```
~/docker/
├── authelia/ # Config SSO
├── caddy/ # Caddyfile + certificats
├── crowdsec/ # Config IDS
├── dockge/ # Stacks Dockge
├── docs/ # MkDocs (cette doc)
├── gitea/ # Config + data Gitea
├── grafana/ # Dashboards
├── homeassistant/ # Config HA
├── languagetool/ # Config LT
├── linkwarden/ # Config Linkwarden
├── outline/ # Config Outline
├── syslog-ng/ # Config syslog
├── talloires/ # Stack principal (docker-compose.yml)
├── uptime-kuma/ # Data Uptime Kuma
├── vikunja/ # Config Vikunja
└── zeronsd/ # DNS ZeroTier
```
## Réseau
| Réseau | Plage | Usage |
|--------|-------|-------|
| ZeroTier | 10.144.0.0/16 | Accès distant |
| Docker talloires_net | 172.20.0.0/16 | Inter-containers |
| LAN physique | 10.171.171.0/24 | Réseau local |
### Adresses ZeroTier clés
| Serveur | IP |
|---------|-----|
| Talloires (Pi5) | 10.144.221.22 |
| Annecy (Synology) | 10.144.78.193 |
| Olympou (Mac) | 10.144.46.46 |
## Stockage
| Mount | Source | Usage |
|-------|--------|-------|
| /mnt/mediaserver | USB SSD 4TB | Films, Séries, Downloads, Databases |
| ~/docker | SD Card | Configs Docker légères |
### Structure USB (/mnt/mediaserver)
```
/mnt/mediaserver/
├── databases/
│ ├── languagetool/ngrams/ # N-grams FR/EN/DE (~8GB)
│ └── outline/
│ ├── data/ # Fichiers Outline
│ ├── postgres/ # PostgreSQL Outline
│ └── redis/ # Redis Outline
├── downloads/ # Transmission
├── movies/ # Films (Jellyfin)
└── series/ # Séries (Jellyfin)
```
## Backup
| Paramètre | Valeur |
|-----------|--------|
| Destination | Annecy (Synology) |
| Schedule | 3h00 quotidien |
| Rétention | 7 jours |
| Méthode | tar over SSH |
Voir [Scripts de maintenance](../reference/scripts.md) pour les détails.
## Maintenance automatique
| Tâche | Schedule | Outil |
|-------|----------|-------|
| Mise à jour containers | 4h00 | Watchtower |
| Backup vers Annecy | 3h00 | backup-to-annecy.sh (cron) |
| Nettoyage images | Après update | docker image prune |

36
mkdocs.yml Normal file
View File

@@ -0,0 +1,36 @@
site_name: Talloires
site_description: Documentation du serveur Talloires
site_url: https://docs.talloires.local
theme:
name: material
palette:
scheme: slate
primary: indigo
accent: indigo
features:
- navigation.instant
- navigation.sections
- navigation.expand
- toc.integrate
extra_javascript:
- javascripts/external-links.js
nav:
- Accueil: index.md
- Services:
- Vue ensemble: services/overview.md
- Authelia SSO: services/authelia.md
- Backup: services/backup.md
- Référence:
- Ports: reference/ports.md
- Commandes: reference/commands.md
- Scripts: reference/scripts.md
markdown_extensions:
- tables
- admonition
- pymdownx.highlight
- pymdownx.superfences
- pymdownx.details