agence66-nextcloud-docker/README.md

# Nextcloud Docker Deployment

Déploiement Nextcloud avec Docker Compose comprenant MariaDB 10.11, Redis (cache), service cron intégré et support Traefik pour le reverse proxy.

## Table des matières

- [Architecture](#architecture)
- [Prérequis](#prérequis)
- [Installation](#installation)
- [Configuration](#configuration)
- [Démarrage](#démarrage)
- [Maintenance](#️-maintenance)
- [Résolution de problèmes](#-résolution-de-problèmes)
- [Monitoring](#-monitoring)
- [Sécurité](#-sécurité)

## Architecture

Le déploiement comprend 4 services:

- **nextcloud**: Application Nextcloud (port 127.0.0.1:8888:80)
- **db**: MariaDB 10.11 avec healthcheck
- **redis**: Cache Redis avec politique LRU (512MB max)
- **cron**: Tâches planifiées Nextcloud (préviews, nettoyage, etc.)

**Réseaux**:

- `nextcloud-net`: Réseau interne pour la communication entre services
- `traefik-net`: Réseau externe pour Traefik (reverse proxy)

## Prérequis

- Docker >= 20.10
- Docker Compose >= 2.0
- Traefik configuré avec réseau `traefik-net` (pour exposition HTTPS)
- Nom de domaine configuré avec certificat SSL
- Minimum 2GB RAM recommandé
- Minimum 10GB d'espace disque

## Installation

1. **Cloner le dépôt**

```bash
git clone <repository-url>
cd agence66-nextcloud-docker
```

2. **Configurer l'environnement**

```bash
cp .env.example .env
nano .env
```

3. **Générer des mots de passe sécurisés**

```bash
# Génération pour chaque secret requis
openssl rand -base64 32
```

Variables importantes à configurer dans `.env`:

- `MYSQL_DATABASE`: Nom de la base de données (défaut: nextcloud)
- `MYSQL_USER`: Utilisateur de la base de données
- `MYSQL_PASSWORD`: Mot de passe de la base de données
- `MYSQL_ROOT_PASSWORD`: Mot de passe root MariaDB
- `REDIS_HOST_PASSWORD`: Mot de passe Redis
- `NEXTCLOUD_DOMAIN`: Votre nom de domaine
- `OVERWRITE_PROTOCOL`: Protocole (http/https)
- `OVERWRITE_HOST`: Hôte public (optionnel)

## Configuration

### Variables d'environnement

Créez votre fichier `.env` basé sur `.env.example`:

| Variable               | Description                 | Exemple             |
| ---------------------- | --------------------------- | ------------------- |
| `MYSQL_DATABASE`       | Nom de la base de données   | `nextcloud`         |
| `MYSQL_USER`           | Utilisateur base de données | `nextcloud`         |
| `MYSQL_PASSWORD`       | Mot de passe utilisateur DB | `********`          |
| `MYSQL_ROOT_PASSWORD`  | Mot de passe root MariaDB   | `********`          |
| `REDIS_HOST_PASSWORD`  | Mot de passe Redis          | `********`          |
| `NEXTCLOUD_DOMAIN`     | Domaine de confiance        | `cloud.example.com` |
| `OVERWRITE_PROTOCOL`   | Protocole (http/https)      | `https`             |
| `OVERWRITE_HOST`       | Hôte public                 | `cloud.example.com` |
| `TRUSTED_PROXIES`      | Proxies de confiance        | `172.18.0.0/16`     |
| `OVERWRITE_CLI_URL`    | URL pour CLI (optionnel)    | `https://...`       |

### Volumes

Les données persistantes sont stockées dans:

- `./data`: Fichiers Nextcloud et données utilisateurs
- `./db`: Base de données MariaDB
- `./db-config`: Configuration MariaDB personnalisée

### Configuration PHP

Les paramètres PHP sont préconfigurés dans docker-compose.yml:

| Paramètre                 | Valeur | Description                     |
| ------------------------- | ------ | ------------------------------- |
| `PHP_MEMORY_LIMIT`        | 4096M  | Mémoire allouée à PHP           |
| `PHP_UPLOAD_MAX_FILESIZE` | 2G     | Taille max d'upload             |
| `PHP_POST_MAX_SIZE`       | 2G     | Taille max POST                 |
| `PHP_MAX_EXECUTION_TIME`  | 1800s  | Timeout d'exécution (30min)     |
| `PHP_MAX_INPUT_TIME`      | 1800s  | Timeout lecture données (30min) |
| `APACHE_BODY_LIMIT`       | 2GB    | Limite Apache pour le body      |

Ces valeurs permettent l'upload de fichiers jusqu'à 2GB.

### Configuration Apache pour Traefik

Le fichier `apache/nextcloud.conf` configure Apache pour fonctionner correctement derrière le reverse proxy Traefik.

**Configuration incluse:**

- **RemoteIP**: Récupération de l'IP réelle du client (pas celle de Traefik)
- **X-Forwarded-Proto**: Détection automatique HTTPS depuis Traefik
- **Headers de sécurité**: X-Frame-Options, X-Content-Type-Options, etc.
- **WebDAV désactivé**: Évite les conflits (Nextcloud gère son propre WebDAV)

**Activation des modules Apache:**

Lors du premier déploiement, activez les modules nécessaires:

```bash
# Activer tous les modules en une commande
docker compose exec nextcloud bash -c "a2enmod headers rewrite dir mime remoteip env && apache2ctl graceful"

# Redémarrer Nextcloud pour appliquer les changements
docker compose restart nextcloud
```

**Modules activés:**

| Module     | Utilité                                              |
| ---------- | ---------------------------------------------------- |
| `headers`  | Gestion des headers HTTP (sécurité)                 |
| `rewrite`  | URL rewriting (requis pour .htaccess)               |
| `dir`      | DirectoryIndex (index.php, etc.)                    |
| `mime`     | Types MIME (CSS, JS, etc.)                          |
| `remoteip` | Récupération IP client via X-Forwarded-For          |
| `env`      | Variables d'environnement (détection HTTPS)         |

**Note**: Les modules `headers`, `rewrite`, `dir`, et `mime` sont normalement activés par défaut dans l'image `nextcloud:latest`. Seuls `remoteip` et `env` doivent être activés manuellement.

**Vérification:**

```bash
# Vérifier qu'Apache utilise bien la configuration
docker compose exec nextcloud apache2ctl -M | grep -E "(headers|rewrite|remoteip|env)"

# Vérifier les logs avec IP réelle
docker compose logs nextcloud --tail=20
```

## Démarrage

### Première installation

```bash
# Démarrer tous les services
make up

# Vérifier que tous les containers sont actifs
make ps

# Vérifier l'état de Nextcloud
make health
```

**Accès à l'instance**:

- **Via Traefik** (production): `https://votre-domaine.com` (recommandé)
- **Accès direct** (développement): `http://localhost:8888`

**Note**: En production, Traefik doit être configuré pour exposer Nextcloud via HTTPS. Le port 8888 n'écoute que sur 127.0.0.1 pour des raisons de sécurité.

### Arrêter les services

```bash
make down
```

### Redémarrer les services

```bash
make restart
```

## 🛠️ Maintenance

### Backup pré-mise à jour

Créer une sauvegarde de sécurité avant une mise à jour:

```bash
make backup
```

**Actions effectuées par le script:**

1. ⏸️  Active le mode maintenance Nextcloud
2. 💾 Sauvegarde la base de données MariaDB (mysqldump avec transactions)
3. ⚙️  Sauvegarde la configuration (`/var/www/html/config`)
4. 📁 Sauvegarde les données utilisateurs (avec exclusions: previews, cache, thumbnails)
5. 📦 Sauvegarde les apps personnalisées (`custom_apps`)
6. ▶️  Désactive le mode maintenance
7. 🗜️  Compresse le tout en `.tar.gz` dans `./backups/`
8. 🧹 Nettoie les backups de plus de 7 jours

**Sécurité:**
- Tous les tar s'exécutent dans le container en tant que `www-data`
- Mots de passe sécurisés via `MYSQL_PWD` (pas visible dans `ps`)
- Cleanup automatique en cas d'erreur avec trap handler

**Note**: Un service cron intégré est déjà configuré dans docker-compose.yml pour les tâches planifiées Nextcloud (préviews, nettoyage, etc.)

### Restauration

```bash
# Lister les backups disponibles
ls -lh backups/

# Restaurer depuis une sauvegarde
make restore backups/nextcloud_backup_YYYYMMDD_HHMMSS.tar.gz
```

**Actions effectuées par le script:**

1. ⚠️  Demande confirmation (opération destructive!)
2. 📂 Extrait l'archive dans un répertoire temporaire
3. ✅ Valide le contenu de l'archive (type MIME, fichiers requis)
4. ⏹️  Arrête tous les services Docker
5. 💾 Restaure la base de données MariaDB
   - Démarre uniquement le container DB
   - Attend que MariaDB soit prêt (health check)
   - Importe le dump SQL
6. ▶️  Démarre tous les services
7. 📁 Restaure les fichiers (config, données, apps) via le container
8. 🔧 Exécute `maintenance:repair` pour corriger les éventuels problèmes
9. ▶️  Désactive le mode maintenance
10. 🔍 Scanne tous les fichiers avec `files:scan --all`
11. 🧹 Nettoie le répertoire temporaire

**Sécurité:**
- Validation du chemin (protection path traversal)
- Vérification du type de fichier (gzip)
- Restauration via container en tant que `www-data`
- Cleanup garanti avec trap handler

### Mise à jour

Mettre à jour Nextcloud vers la dernière version:

```bash
make update
```

**Le script effectue automatiquement un backup avant la mise à jour!**

**Actions effectuées par le script:**

1. 💾 **Backup automatique de sécurité**
   - Exécute `scripts/backup.sh` complet
   - Archive créée dans `./backups/`
2. 📥 Télécharge la nouvelle image Docker Nextcloud
3. ⏸️  Active le mode maintenance
4. 🔄 Redémarre les containers avec `--force-recreate`
5. ⏳ Attend que Nextcloud soit prêt (health check jusqu'à 60s)
6. ▶️  Désactive temporairement le mode maintenance
7. ⬆️  Exécute `occ upgrade` (migrations base de données)
8. 🔍 Scanne tous les fichiers (`files:scan --all`)
9. 📊 Ajoute les indices manquants (`db:add-missing-indices`)
10. 🔧 Convertit les colonnes en bigint (`db:convert-filecache-bigint`)
11. ▶️  Désactive le mode maintenance
12. ✅ Affiche le statut final

**Vérification post-update:**

```bash
# Vérifier la version et l'état
make occ status

# Vérifier la santé globale
make health
```

**En cas de problème:**

Si la mise à jour échoue, restaurez le backup automatique créé à l'étape 1:

```bash
# Lister les backups (le plus récent est celui de l'update)
ls -lht backups/ | head

# Restaurer
make restore backups/nextcloud_backup_YYYYMMDD_HHMMSS.tar.gz
```

**Sécurité:**
- Backup automatique avant toute modification
- Trap handler pour cleanup en cas d'erreur
- Mode maintenance automatiquement désactivé même en cas d'échec
- Instructions de rollback affichées en cas d'erreur

### Commandes OCC

OCC (occ = ownCloud Console) est l'interface en ligne de commande de Nextcloud:

```bash
# Vérifier le status de l'instance
make occ status

# Lister les utilisateurs
make occ user:list

# Scanner tous les fichiers
make occ files:scan --all

# Lister les applications installées
make occ app:list

# Activer/désactiver le mode maintenance
make occ maintenance:mode --on
make occ maintenance:mode --off
```

## 🔧 Résolution de problèmes

### Erreur 423 WebDAV Locked

Si vous rencontrez des erreurs de fichiers verrouillés:

```bash
make occ files:cleanup
```

### Performance lente

Optimisations recommandées:

```bash
# Ajouter les indices manquants en base de données
make occ db:add-missing-indices

# Convertir les colonnes en big int si nécessaire
make occ db:convert-filecache-bigint

# Nettoyer les fichiers supprimés
make occ files:cleanup

# Optimiser la génération des previews
make occ config:app:set previewgenerator squareSizes --value="256 512"
make occ config:app:set previewgenerator widthSizes --value="256 512 1024"
make occ config:app:set previewgenerator heightSizes --value="256 512 1024"

# Générer les previews
make occ preview:generate-all
```

### Problèmes de permissions

```bash
# Réparer les permissions des fichiers
docker compose exec -u www-data nextcloud chown -R www-data:www-data /var/www/html/data
```

### Espace disque insuffisant

```bash
# Nettoyer les anciennes versions de fichiers
make occ versions:cleanup

# Nettoyer la corbeille
make occ trashbin:cleanup --all-users

# Vérifier l'utilisation de l'espace
du -sh ./data  # Données Nextcloud
du -sh ./db    # Base de données MariaDB
```

### Mode débogage

⚠️ **IMPORTANT**: Le mode débogage ne doit **JAMAIS** être activé en production!

**Vérifier l'état du mode débogage:**

```bash
make occ config:system:get debug
```

**Désactiver le mode débogage (PRODUCTION):**

```bash
# Via OCC (recommandé)
make occ config:system:set debug --value=false --type=boolean

# OU éditer manuellement config.php
docker-compose exec nextcloud nano /var/www/html/config/config.php
# Chercher 'debug' => true, et changer en false ou supprimer la ligne
```

**Activer temporairement pour diagnostiquer un problème (DÉVELOPPEMENT UNIQUEMENT):**

```bash
# Activer
make occ config:system:set debug --value=true --type=boolean

# IMPORTANT: Désactiver immédiatement après le diagnostic!
make occ config:system:set debug --value=false --type=boolean
```

**Pourquoi c'est dangereux en production:**

- 🚨 **Sécurité**: Expose des informations sensibles (chemins, configuration, requêtes SQL)
- 🐌 **Performance**: Génère énormément de logs et ralentit l'application
- 💾 **Espace disque**: Remplit rapidement le disque avec des logs détaillés
- 📊 **Conformité**: Peut logger des données personnelles (RGPD)

### Messages de debug dans la console navigateur

Si vous voyez des messages `[DEBUG]` dans la console JavaScript du navigateur (F12), même avec `debug => false`:

**1. Vider tous les caches:**

```bash
# Cache Nextcloud
make occ maintenance:repair --include-expensive

# Cache Redis
docker compose exec redis redis-cli -a VOTRE_PASSWORD_REDIS FLUSHALL
```

**2. Vérifier le niveau de log:**

```bash
# Niveau recommandé pour production: 2 (Warning)
make occ config:system:set loglevel --value=2 --type=integer
```

**Niveaux de log disponibles:**
- 0 = Debug (tous les messages)
- 1 = Info
- 2 = Warning (recommandé production)
- 3 = Error
- 4 = Fatal

**3. Hard refresh dans le navigateur:**

```bash
# Firefox/Chrome: Ctrl + Shift + R
# Ou vider le cache du navigateur pour le domaine Nextcloud
```

**4. Redémarrer les services:**

```bash
docker compose restart nextcloud redis
```

### Problèmes de synchronisation client

Si le client de synchronisation Nextcloud affiche "error transfering, server replied not found":

**1. Scanner les fichiers pour mettre à jour l'index:**

```bash
# Scanner tous les fichiers d'un utilisateur
make occ files:scan nom_utilisateur

# Scanner uniquement un dossier spécifique
make occ files:scan --path="/nom_utilisateur/files/Dossier"
```

**2. Nettoyer les verrous de fichiers:**

```bash
make occ files:cleanup
```

**3. Vérifier les logs pour identifier le fichier problématique:**

```bash
# Logs en temps réel
docker compose logs -f nextcloud --tail=50

# Rechercher les erreurs 404
docker compose logs nextcloud | grep "404"
```

**4. En dernier recours, réinitialiser la synchronisation:**
- Dans le client Nextcloud: supprimer le compte et le re-configurer
- Cela forcera une synchronisation complète

## 📊 Monitoring

### Vérifications de santé

```bash
# Status général
make health

# Vérifier les containers actifs
make ps

# Voir les logs en temps réel
make logs

# Logs d'un service spécifique
docker compose logs -f nextcloud
docker compose logs -f db
docker compose logs -f redis
```

### Métriques de performance

```bash
# Statistiques système
make occ status

# Informations sur la base de données MariaDB
docker compose exec db mysql -u${MYSQL_USER} -p${MYSQL_PASSWORD} -e "SELECT table_schema AS 'Database', ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) AS 'Size (MB)' FROM information_schema.TABLES WHERE table_schema = 'nextcloud';"

# Utilisation Redis
docker compose exec redis redis-cli -a ${REDIS_HOST_PASSWORD} INFO stats
```

## 🔒 Sécurité

### Bonnes pratiques

1. **Mots de passe forts**: Utilisez `openssl rand -base64 32` pour tous les secrets
2. **HTTPS obligatoire**: Configurez SSL/TLS avec Let's Encrypt ou certificats valides
3. **Mises à jour régulières**: Exécutez `make backup` puis `make update` mensuellement
4. **Sauvegardes**: Utilisez `make backup` avant toute mise à jour (backup serveur quotidien géré au niveau système)
5. **Monitoring**: Vérifiez les logs régulièrement pour détecter les activités suspectes
6. **Mode débogage désactivé**: Vérifiez avec `make occ config:system:get debug` (doit être `false` ou absent)

### Sécuriser l'accès

```bash
# Activer l'authentification à deux facteurs
make occ app:enable twofactor_totp

# Forcer HTTPS
make occ config:system:set overwriteprotocol --value="https"

# Limiter les tentatives de connexion
make occ app:enable bruteforcesettings
```

## Commandes Make disponibles

| Commande                   | Description                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `make up`                  | Démarrer tous les services Docker (nextcloud, db, redis, cron)                                  |
| `make down`                | Arrêter et supprimer tous les containers                                                        |
| `make restart`             | Redémarrer tous les services                                                                    |
| `make ps`                  | Lister les containers actifs avec leur état                                                     |
| `make logs`                | Afficher les logs Nextcloud en temps réel (tail -100)                                           |
| `make health`              | Vérifier l'état: statut Nextcloud + config système + connexion MariaDB                          |
| `make backup`              | Backup complet: DB + config + données + apps (avec mode maintenance)                            |
| `make restore <file>`      | Restaurer depuis un backup (destructif - demande confirmation)                                  |
| `make update`              | Mise à jour complète: backup auto + pull + upgrade + optimisations                              |
| `make occ <commande>`      | Exécuter une commande OCC Nextcloud (ex: `make occ user:list`)                                  |

**Exemples d'utilisation:**

```bash
# Backup et update
make backup
make update

# Restaurer un backup spécifique
make restore backups/nextcloud_backup_20251215_112450.tar.gz

# Commandes OCC
make occ status
make occ user:list
make occ files:scan --all
```

## Support

Pour toute question ou problème:

1. Consultez la [documentation officielle Nextcloud](https://docs.nextcloud.com/)
2. Vérifiez les logs: `make logs`
3. Consultez les issues du projet