|
|
@@ -0,0 +1,539 @@
|
|
|
+# 🚀 Guide de Migration vers MariaDB - Version Complète
|
|
|
+
|
|
|
+## 📋 Vue d'ensemble
|
|
|
+
|
|
|
+Ce guide vous accompagne pour migrer votre blog Django de SQLite vers MariaDB sur votre Raspberry Pi.
|
|
|
+
|
|
|
+### Prérequis
|
|
|
+- ✅ Serveur MariaDB dans Docker sur le RPI (conteneur nommé `mariadb`)
|
|
|
+- ✅ Accès réseau du Mac vers le RPI
|
|
|
+- ✅ Python 3.x installé
|
|
|
+- ✅ Fichier `.env` configuré
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🎯 Étape 1 : Vérifications préliminaires
|
|
|
+
|
|
|
+### 1.1 Vérifier l'environnement
|
|
|
+
|
|
|
+```bash
|
|
|
+# Rendre le script exécutable
|
|
|
+chmod +x scripts/pre_migration_check.sh
|
|
|
+
|
|
|
+# Lancer les vérifications
|
|
|
+./scripts/pre_migration_check.sh
|
|
|
+```
|
|
|
+
|
|
|
+Ce script vérifie :
|
|
|
+- ✅ Python et dépendances installées
|
|
|
+- ✅ Configuration du fichier `.env`
|
|
|
+- ✅ Connexion réseau vers MariaDB
|
|
|
+- ✅ Présence de la base SQLite source
|
|
|
+
|
|
|
+### 1.2 Installer les dépendances manquantes
|
|
|
+
|
|
|
+Si des dépendances manquent :
|
|
|
+
|
|
|
+```bash
|
|
|
+pip3 install -r requirements.txt
|
|
|
+```
|
|
|
+
|
|
|
+**Important**: `mysqlclient` nécessite des outils de compilation :
|
|
|
+
|
|
|
+**Sur macOS :**
|
|
|
+```bash
|
|
|
+brew install mysql-client pkg-config
|
|
|
+export PKG_CONFIG_PATH="/opt/homebrew/opt/mysql-client/lib/pkgconfig"
|
|
|
+pip3 install mysqlclient
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🔧 Étape 2 : Configuration du serveur MariaDB
|
|
|
+
|
|
|
+### 2.1 Vérifier que le conteneur Docker est démarré
|
|
|
+
|
|
|
+Sur votre **Raspberry Pi** :
|
|
|
+
|
|
|
+```bash
|
|
|
+# Vérifier si le conteneur tourne
|
|
|
+docker ps | grep mariadb
|
|
|
+
|
|
|
+# Si non démarré, le démarrer
|
|
|
+docker start mariadb
|
|
|
+
|
|
|
+# Voir les logs
|
|
|
+docker logs mariadb
|
|
|
+```
|
|
|
+
|
|
|
+### 2.2 Vérifier l'exposition du port
|
|
|
+
|
|
|
+```bash
|
|
|
+# Sur le RPI
|
|
|
+docker port mariadb
|
|
|
+# Devrait afficher : 3306/tcp -> 0.0.0.0:3306
|
|
|
+```
|
|
|
+
|
|
|
+Si le port n'est pas exposé, recréez le conteneur :
|
|
|
+
|
|
|
+```bash
|
|
|
+docker run -d \
|
|
|
+ --name mariadb \
|
|
|
+ -p 3306:3306 \
|
|
|
+ -e MYSQL_ROOT_PASSWORD=votre_mot_de_passe_root \
|
|
|
+ -v mariadb_data:/var/lib/mysql \
|
|
|
+ --restart unless-stopped \
|
|
|
+ mariadb:latest
|
|
|
+```
|
|
|
+
|
|
|
+### 2.3 Créer la base de données et l'utilisateur
|
|
|
+
|
|
|
+Sur le **Raspberry Pi** :
|
|
|
+
|
|
|
+```bash
|
|
|
+# Se connecter à MariaDB
|
|
|
+docker exec -it mariadb mysql -u root -p
|
|
|
+```
|
|
|
+
|
|
|
+Puis dans le shell MySQL :
|
|
|
+
|
|
|
+```sql
|
|
|
+-- Créer la base de données
|
|
|
+CREATE DATABASE IF NOT EXISTS duhaz_blog
|
|
|
+ CHARACTER SET utf8mb4
|
|
|
+ COLLATE utf8mb4_unicode_ci;
|
|
|
+
|
|
|
+-- Créer l'utilisateur
|
|
|
+CREATE USER IF NOT EXISTS 'duhaz_user'@'%'
|
|
|
+ IDENTIFIED BY 'votre_mot_de_passe_securise';
|
|
|
+
|
|
|
+-- Donner tous les droits sur la base
|
|
|
+GRANT ALL PRIVILEGES ON duhaz_blog.* TO 'duhaz_user'@'%';
|
|
|
+
|
|
|
+-- Appliquer les changements
|
|
|
+FLUSH PRIVILEGES;
|
|
|
+
|
|
|
+-- Vérifier
|
|
|
+SHOW DATABASES;
|
|
|
+SELECT User, Host FROM mysql.user WHERE User = 'duhaz_user';
|
|
|
+
|
|
|
+-- Quitter
|
|
|
+EXIT;
|
|
|
+```
|
|
|
+
|
|
|
+**Note**: `'duhaz_user'@'%'` permet les connexions depuis n'importe quelle IP. Pour plus de sécurité, remplacez `%` par l'IP de votre Mac.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🌐 Étape 3 : Configuration réseau
|
|
|
+
|
|
|
+### 3.1 Trouver l'IP de votre Raspberry Pi
|
|
|
+
|
|
|
+Sur le **RPI** :
|
|
|
+
|
|
|
+```bash
|
|
|
+hostname -I
|
|
|
+# Exemple de résultat : 192.168.1.100
|
|
|
+```
|
|
|
+
|
|
|
+### 3.2 Tester la connexion réseau
|
|
|
+
|
|
|
+Depuis votre **Mac** :
|
|
|
+
|
|
|
+```bash
|
|
|
+# Test de ping
|
|
|
+ping 192.168.1.100
|
|
|
+
|
|
|
+# Test du port MariaDB
|
|
|
+nc -zv 192.168.1.100 3306
|
|
|
+# ou
|
|
|
+telnet 192.168.1.100 3306
|
|
|
+```
|
|
|
+
|
|
|
+Si le port n'est pas accessible, vérifiez :
|
|
|
+- Le pare-feu du RPI : `sudo ufw status`
|
|
|
+- Le conteneur Docker expose bien le port
|
|
|
+- Votre réseau local autorise les connexions
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## ⚙️ Étape 4 : Configuration du fichier .env
|
|
|
+
|
|
|
+### 4.1 Éditer le fichier .env
|
|
|
+
|
|
|
+Deux options pour `DB_HOST` :
|
|
|
+
|
|
|
+**Option A : Utiliser le nom du conteneur** (si votre Mac fait partie du réseau Docker)
|
|
|
+```env
|
|
|
+DB_ENGINE=mysql
|
|
|
+DB_NAME=duhaz_blog
|
|
|
+DB_USER=duhaz_user
|
|
|
+DB_PASSWORD=votre_mot_de_passe_securise
|
|
|
+DB_HOST=mariadb
|
|
|
+DB_PORT=3306
|
|
|
+```
|
|
|
+
|
|
|
+**Option B : Utiliser l'IP du RPI** (recommandé pour développement depuis un autre machine)
|
|
|
+```env
|
|
|
+DB_ENGINE=mysql
|
|
|
+DB_NAME=duhaz_blog
|
|
|
+DB_USER=duhaz_user
|
|
|
+DB_PASSWORD=votre_mot_de_passe_securise
|
|
|
+DB_HOST=192.168.1.100
|
|
|
+DB_PORT=3306
|
|
|
+```
|
|
|
+
|
|
|
+### 4.2 Sécurité du mot de passe
|
|
|
+
|
|
|
+⚠️ **Important** : N'utilisez JAMAIS de mots de passe simples en production !
|
|
|
+
|
|
|
+Générer un mot de passe fort :
|
|
|
+```bash
|
|
|
+openssl rand -base64 32
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🧪 Étape 5 : Test de connexion
|
|
|
+
|
|
|
+### 5.1 Test direct avec Python
|
|
|
+
|
|
|
+```bash
|
|
|
+python3 scripts/test_mariadb_connection.py
|
|
|
+```
|
|
|
+
|
|
|
+Ce script teste :
|
|
|
+1. Import du module MySQLdb
|
|
|
+2. Connexion directe à MariaDB
|
|
|
+3. Connexion via Django
|
|
|
+
|
|
|
+### 5.2 Interpréter les résultats
|
|
|
+
|
|
|
+**✅ Succès** :
|
|
|
+```
|
|
|
+✅ Tous les tests sont passés!
|
|
|
+```
|
|
|
+
|
|
|
+**❌ Échec** - Erreurs courantes :
|
|
|
+
|
|
|
+| Erreur | Solution |
|
|
|
+|--------|----------|
|
|
|
+| `ModuleNotFoundError: No module named 'MySQLdb'` | `pip3 install mysqlclient` |
|
|
|
+| `Can't connect to MySQL server` | Vérifier que MariaDB est démarré et accessible |
|
|
|
+| `Access denied for user` | Vérifier DB_USER et DB_PASSWORD dans .env |
|
|
|
+| `Unknown database` | Créer la base avec les commandes SQL ci-dessus |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 📦 Étape 6 : Sauvegarde des données SQLite
|
|
|
+
|
|
|
+### 6.1 Sauvegarde automatique
|
|
|
+
|
|
|
+Le script de migration crée automatiquement un backup, mais vous pouvez aussi le faire manuellement :
|
|
|
+
|
|
|
+```bash
|
|
|
+# Créer le dossier de backup
|
|
|
+mkdir -p backup
|
|
|
+
|
|
|
+# Copier la base SQLite
|
|
|
+cp db.sqlite3 backup/db.sqlite3.backup
|
|
|
+
|
|
|
+# Export JSON des données
|
|
|
+python3 manage.py dumpdata \
|
|
|
+ --natural-foreign \
|
|
|
+ --natural-primary \
|
|
|
+ --exclude=contenttypes \
|
|
|
+ --exclude=auth.permission \
|
|
|
+ --indent=2 \
|
|
|
+ --output=backup/sqlite_data.json
|
|
|
+```
|
|
|
+
|
|
|
+### 6.2 Vérifier le backup
|
|
|
+
|
|
|
+```bash
|
|
|
+# Taille du fichier
|
|
|
+ls -lh backup/
|
|
|
+
|
|
|
+# Nombre d'objets dans le JSON
|
|
|
+grep -c '"model":' backup/sqlite_data.json
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🚀 Étape 7 : Migration des données
|
|
|
+
|
|
|
+### 7.1 Lancer la migration automatique
|
|
|
+
|
|
|
+```bash
|
|
|
+python3 scripts/migrate_to_mariadb.py
|
|
|
+```
|
|
|
+
|
|
|
+Le script effectue :
|
|
|
+1. **Export** des données depuis SQLite
|
|
|
+2. **Pause** pour que vous modifiiez le .env vers MariaDB
|
|
|
+3. **Import** des données dans MariaDB
|
|
|
+4. **Vérification** du nombre d'enregistrements
|
|
|
+
|
|
|
+### 7.2 Processus étape par étape
|
|
|
+
|
|
|
+Le script vous demandera :
|
|
|
+
|
|
|
+```
|
|
|
+⚠️ IMPORTANT: Maintenant, modifiez votre fichier .env
|
|
|
+Changez DB_ENGINE de 'sqlite3' à 'mysql'
|
|
|
+Appuyez sur Entrée quand c'est fait...
|
|
|
+```
|
|
|
+
|
|
|
+À ce moment :
|
|
|
+1. Éditez le fichier `.env`
|
|
|
+2. Changez `DB_ENGINE=sqlite3` vers `DB_ENGINE=mysql`
|
|
|
+3. Appuyez sur Entrée dans le terminal
|
|
|
+
|
|
|
+### 7.3 Migration manuelle (si nécessaire)
|
|
|
+
|
|
|
+Si vous préférez contrôler chaque étape :
|
|
|
+
|
|
|
+```bash
|
|
|
+# 1. Exporter depuis SQLite (avec DB_ENGINE=sqlite3)
|
|
|
+python3 manage.py dumpdata \
|
|
|
+ --natural-foreign \
|
|
|
+ --natural-primary \
|
|
|
+ --exclude=contenttypes \
|
|
|
+ --exclude=auth.permission \
|
|
|
+ --indent=2 \
|
|
|
+ --output=backup/manual_export.json
|
|
|
+
|
|
|
+# 2. Modifier le .env pour passer à MariaDB
|
|
|
+# DB_ENGINE=mysql
|
|
|
+
|
|
|
+# 3. Créer les tables dans MariaDB
|
|
|
+python3 manage.py migrate --run-syncdb
|
|
|
+
|
|
|
+# 4. Importer les données
|
|
|
+python3 manage.py loaddata backup/manual_export.json
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## ✅ Étape 8 : Vérification post-migration
|
|
|
+
|
|
|
+### 8.1 Vérifier les données
|
|
|
+
|
|
|
+```bash
|
|
|
+# Lancer le shell Django
|
|
|
+python3 manage.py shell
|
|
|
+```
|
|
|
+
|
|
|
+Dans le shell Python :
|
|
|
+
|
|
|
+```python
|
|
|
+from django.contrib.auth.models import User
|
|
|
+from blog.models import Article
|
|
|
+
|
|
|
+# Compter les utilisateurs
|
|
|
+print(f"Utilisateurs: {User.objects.count()}")
|
|
|
+
|
|
|
+# Compter les articles
|
|
|
+print(f"Articles: {Article.objects.count()}")
|
|
|
+
|
|
|
+# Afficher le premier article
|
|
|
+article = Article.objects.first()
|
|
|
+if article:
|
|
|
+ print(f"Premier article: {article.title}")
|
|
|
+```
|
|
|
+
|
|
|
+### 8.2 Tester l'interface admin
|
|
|
+
|
|
|
+```bash
|
|
|
+# Démarrer le serveur
|
|
|
+python3 manage.py runserver
|
|
|
+```
|
|
|
+
|
|
|
+Accédez à : http://127.0.0.1:8000/admin/
|
|
|
+
|
|
|
+Vérifiez :
|
|
|
+- ✅ Connexion avec votre compte admin
|
|
|
+- ✅ Liste des articles visible
|
|
|
+- ✅ Modification d'un article fonctionne
|
|
|
+- ✅ Création d'un nouvel article fonctionne
|
|
|
+
|
|
|
+### 8.3 Tester le site public
|
|
|
+
|
|
|
+Accédez à : http://127.0.0.1:8000/
|
|
|
+
|
|
|
+Vérifiez :
|
|
|
+- ✅ Les articles s'affichent
|
|
|
+- ✅ Les images sont visibles
|
|
|
+- ✅ Les liens fonctionnent
|
|
|
+- ✅ La recherche fonctionne
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🔧 Dépannage
|
|
|
+
|
|
|
+### Problème : Can't connect to MySQL server
|
|
|
+
|
|
|
+**Cause** : Le serveur n'est pas accessible
|
|
|
+
|
|
|
+**Solutions** :
|
|
|
+```bash
|
|
|
+# 1. Vérifier que le conteneur tourne
|
|
|
+docker ps | grep mariadb
|
|
|
+
|
|
|
+# 2. Voir les logs
|
|
|
+docker logs mariadb
|
|
|
+
|
|
|
+# 3. Tester la connexion réseau
|
|
|
+telnet 192.168.1.100 3306
|
|
|
+
|
|
|
+# 4. Vérifier le pare-feu
|
|
|
+sudo ufw status
|
|
|
+```
|
|
|
+
|
|
|
+### Problème : Access denied for user
|
|
|
+
|
|
|
+**Cause** : Identifiants incorrects
|
|
|
+
|
|
|
+**Solutions** :
|
|
|
+```bash
|
|
|
+# Vérifier les variables dans .env
|
|
|
+cat .env | grep DB_
|
|
|
+
|
|
|
+# Tester la connexion directement
|
|
|
+docker exec -it mariadb mysql -u duhaz_user -p
|
|
|
+```
|
|
|
+
|
|
|
+### Problème : Unknown database 'duhaz_blog'
|
|
|
+
|
|
|
+**Cause** : La base n'existe pas
|
|
|
+
|
|
|
+**Solution** :
|
|
|
+```bash
|
|
|
+# Se connecter en root
|
|
|
+docker exec -it mariadb mysql -u root -p
|
|
|
+
|
|
|
+# Créer la base
|
|
|
+CREATE DATABASE duhaz_blog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
|
|
+```
|
|
|
+
|
|
|
+### Problème : Table already exists
|
|
|
+
|
|
|
+**Cause** : Les migrations ont déjà été appliquées
|
|
|
+
|
|
|
+**Solution** :
|
|
|
+```bash
|
|
|
+# Supprimer toutes les tables et recommencer
|
|
|
+docker exec -it mariadb mysql -u root -p
|
|
|
+
|
|
|
+DROP DATABASE duhaz_blog;
|
|
|
+CREATE DATABASE duhaz_blog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
|
|
+
|
|
|
+# Relancer la migration
|
|
|
+python3 scripts/migrate_to_mariadb.py
|
|
|
+```
|
|
|
+
|
|
|
+### Problème : ImportError: No module named 'MySQLdb'
|
|
|
+
|
|
|
+**Cause** : mysqlclient n'est pas installé
|
|
|
+
|
|
|
+**Solution macOS** :
|
|
|
+```bash
|
|
|
+# Installer les dépendances système
|
|
|
+brew install mysql-client pkg-config
|
|
|
+
|
|
|
+# Configurer PKG_CONFIG_PATH
|
|
|
+export PKG_CONFIG_PATH="/opt/homebrew/opt/mysql-client/lib/pkgconfig"
|
|
|
+
|
|
|
+# Installer mysqlclient
|
|
|
+pip3 install mysqlclient
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 📊 Comparaison SQLite vs MariaDB
|
|
|
+
|
|
|
+| Caractéristique | SQLite | MariaDB |
|
|
|
+|----------------|--------|---------|
|
|
|
+| **Performance lecture** | Excellente | Très bonne |
|
|
|
+| **Performance écriture** | Bonne | Excellente |
|
|
|
+| **Concurrence** | Limitée | Excellente |
|
|
|
+| **Backup** | Copie de fichier | mysqldump |
|
|
|
+| **Taille max** | ~140 To | Pratiquement illimitée |
|
|
|
+| **Adapté pour** | Dev, petits sites | Production, sites moyens/grands |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🔒 Sécurité en production
|
|
|
+
|
|
|
+Avant de déployer en production, modifiez `.env` :
|
|
|
+
|
|
|
+```env
|
|
|
+# Désactiver le mode debug
|
|
|
+DEBUG=False
|
|
|
+
|
|
|
+# Limiter les hôtes autorisés
|
|
|
+ALLOWED_HOSTS=duhaz.fr,www.duhaz.fr
|
|
|
+
|
|
|
+# Utiliser un mot de passe fort
|
|
|
+DB_PASSWORD=<mot_de_passe_généré_par_openssl>
|
|
|
+```
|
|
|
+
|
|
|
+Et dans `settings.py`, décommentez :
|
|
|
+
|
|
|
+```python
|
|
|
+SECURE_SSL_REDIRECT = True
|
|
|
+SESSION_COOKIE_SECURE = True
|
|
|
+CSRF_COOKIE_SECURE = True
|
|
|
+SECURE_BROWSER_XSS_FILTER = True
|
|
|
+SECURE_CONTENT_TYPE_NOSNIFF = True
|
|
|
+X_FRAME_OPTIONS = 'DENY'
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 📚 Ressources
|
|
|
+
|
|
|
+### Documentation officielle
|
|
|
+- [Django Database Configuration](https://docs.djangoproject.com/en/5.1/ref/databases/)
|
|
|
+- [MariaDB Knowledge Base](https://mariadb.com/kb/en/)
|
|
|
+- [mysqlclient Documentation](https://mysqlclient.readthedocs.io/)
|
|
|
+
|
|
|
+### Fichiers du projet
|
|
|
+- `scripts/pre_migration_check.sh` - Vérifications préliminaires
|
|
|
+- `scripts/test_mariadb_connection.py` - Test de connexion
|
|
|
+- `scripts/migrate_to_mariadb.py` - Migration automatique
|
|
|
+- `scripts/setup_mariadb.sh` - Configuration du serveur
|
|
|
+- `scripts/setup_mariadb.sql` - Commandes SQL
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## ✨ Checklist finale
|
|
|
+
|
|
|
+Avant de considérer la migration terminée :
|
|
|
+
|
|
|
+- [ ] Tous les tests de connexion passent
|
|
|
+- [ ] L'admin Django fonctionne
|
|
|
+- [ ] Les articles s'affichent sur le site
|
|
|
+- [ ] Les images sont visibles
|
|
|
+- [ ] Les modifications sont sauvegardées
|
|
|
+- [ ] Un backup de SQLite est conservé
|
|
|
+- [ ] Le fichier `.env` est sécurisé
|
|
|
+- [ ] Les mots de passe sont forts
|
|
|
+- [ ] La documentation est à jour
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🆘 Besoin d'aide ?
|
|
|
+
|
|
|
+Si vous rencontrez des problèmes :
|
|
|
+
|
|
|
+1. Consultez la section **Dépannage** ci-dessus
|
|
|
+2. Vérifiez les logs : `docker logs mariadb`
|
|
|
+3. Testez chaque étape individuellement
|
|
|
+4. Gardez votre backup SQLite jusqu'à ce que tout fonctionne
|
|
|
+
|
|
|
+**Rappel important** : Ne supprimez JAMAIS `db.sqlite3` avant d'avoir vérifié que tout fonctionne parfaitement avec MariaDB !
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+Bonne migration ! 🚀
|