init_guac

guacamole_test_11_26/docs/AUTO_DEPLOY_GUIDE.md

@@ -0,0 +1,351 @@
+# 🚀 Автоматический деплой с безопасным администратором
+
+## 🎯 Что делает автоматический деплой?
+
+При запуске `deploy.sh` (Linux/Mac) или `deploy.ps1` (Windows) скрипт **автоматически:**
+
+1. ✅ Проверяет наличие Docker, Python, Docker Compose
+2. ✅ Загружает `.env` или `production.env`
+3. ✅ **Проверяет пароль администратора**
+   - Если пароль **не дефолтный** → генерирует SQL с вашим паролем
+   - Если дефолтный → предупреждает и спрашивает подтверждение
+4. ✅ Создает backup оригинального SQL
+5. ✅ Заменяет `002-create-admin-user.sql` на сгенерированный
+6. ✅ Запускает контейнеры
+7. ✅ Ждет готовности сервисов
+8. ✅ Проверяет что администратор создался
+9. ✅ Выводит итоговую информацию
+
+**Результат:** Безопасный деплой **одной командой** без ручных действий!
+
+---
+
+## ⚡ Быстрый старт
+
+### **Linux/Mac:**
+
+```bash
+cd GuacamoleRemoteAccess
+
+# 1. Обновите production.env с безопасным паролем
+nano production.env
+# SYSTEM_ADMIN_USERNAME=guacadmin
+# SYSTEM_ADMIN_PASSWORD=YourSecurePassword123!
+
+# 2. Запустите deploy скрипт
+chmod +x deploy.sh
+./deploy.sh
+```
+
+### **Windows (PowerShell):**
+
+```powershell
+cd GuacamoleRemoteAccess
+
+# 1. Обновите production.env с безопасным паролем
+notepad production.env
+# SYSTEM_ADMIN_USERNAME=guacadmin
+# SYSTEM_ADMIN_PASSWORD=YourSecurePassword123!
+
+# 2. Запустите deploy скрипт
+.\deploy.ps1
+```
+
+**Вот и всё!** Скрипт сделает остальное.
+
+---
+
+## 📊 Пример работы скрипта
+
+```bash
+$ ./deploy.sh
+
+==========================================
+   Remote Access API Deployment
+==========================================
+
+[INFO] Checking requirements...
+[OK] All requirements met
+[INFO] Loading environment variables...
+[INFO] Using production.env
+[OK] Environment loaded from production.env
+[INFO] Checking admin credentials...
+[OK] Custom password detected - generating secure admin SQL
+[INFO] Username: guacadmin
+[INFO] Password length: 24 characters
+[INFO] Creating backup of default SQL...
+[OK] Backup created: 002-create-admin-user-DEFAULT-BACKUP.sql
+[INFO] Generating SQL with custom password...
+[VERIFY] Verifying hash generation...
+[OK] Hash generation verified
+[OK] Admin SQL generated and applied
+[INFO] File: 002-create-admin-user.sql (auto-generated)
+[INFO] Validating docker-compose.yml...
+[OK] docker-compose.yml is valid
+[INFO] Starting containers...
+[OK] Containers started successfully
+[INFO] Waiting for services to be ready...
+[INFO] Waiting for PostgreSQL...
+[OK] PostgreSQL is ready
+[INFO] Waiting for Guacamole...
+[OK] Guacamole is ready
+[INFO] Waiting for API...
+[OK] API is ready
+[INFO] Verifying deployment...
+[OK] Admin user 'guacadmin' exists in database
+[OK] API successfully authenticated with system credentials
+
+==========================================
+   Deployment Complete!
+==========================================
+
+[OK] Services are running
+
+Access URLs:
+  - Guacamole UI: http://localhost:8080/guacamole/
+  - API Docs: http://localhost:8000/docs (if enabled)
+
+Admin Credentials:
+  - Username: guacadmin
+  - Password: You***rd! (length: 24)
+
+Useful Commands:
+  - View logs: docker compose logs -f
+  - Stop: docker compose down
+  - Restart: docker compose restart
+
+[INFO] Original SQL backed up to: 002-create-admin-user-DEFAULT-BACKUP.sql
+```
+
+---
+
+## 🔐 Проверка безопасности
+
+Скрипт **автоматически проверяет** небезопасные пароли:
+
+### **❌ Будет предупреждение:**
+
+```env
+SYSTEM_ADMIN_PASSWORD=guacadmin
+SYSTEM_ADMIN_PASSWORD=guacadmin_change_in_production
+SYSTEM_ADMIN_PASSWORD=CHANGE_ME_SECURE_PASSWORD_HERE_
+```
+
+**Вывод:**
+```
+[WARNING] Default or placeholder password detected!
+[WARNING] Username: guacadmin
+[WARNING] Password: guacadmin
+[WARNING]
+[WARNING] This is INSECURE for production!
+[WARNING] Using default 002-create-admin-user.sql
+[WARNING]
+Continue anyway? (y/N):
+```
+
+### **✅ Будет генерация:**
+
+```env
+SYSTEM_ADMIN_PASSWORD=MySecureRandomPassword2025!
+```
+
+**Вывод:**
+```
+[OK] Custom password detected - generating secure admin SQL
+[INFO] Username: guacadmin
+[INFO] Password length: 27 characters
+```
+
+---
+
+## 📁 Что происходит с файлами?
+
+### **До деплоя:**
+
+```
+GuacamoleRemoteAccess/
+├── 002-create-admin-user.sql          ← Оригинальный (дефолтный пароль)
+├── generate_guacamole_user.py
+├── production.env
+└── deploy.sh
+```
+
+### **После деплоя:**
+
+```
+GuacamoleRemoteAccess/
+├── 002-create-admin-user.sql          ← ЗАМЕНЕН на сгенерированный
+├── 002-create-admin-user-DEFAULT-BACKUP.sql  ← Backup оригинала
+├── generate_guacamole_user.py
+├── production.env
+└── deploy.sh
+```
+
+**Важно:**
+- ✅ `002-create-admin-user-DEFAULT-BACKUP.sql` - это backup оригинала (коммитится в git)
+- ❌ `002-create-admin-user.sql` - после генерации содержит ваш пароль (**не коммитится!**)
+
+Если нужно восстановить оригинал:
+```bash
+cp 002-create-admin-user-DEFAULT-BACKUP.sql 002-create-admin-user.sql
+```
+
+---
+
+## 🔄 Повторный деплой
+
+При повторном запуске `deploy.sh`:
+
+1. ✅ Проверяет пароль в `.env`
+2. ✅ Если пароль **изменился** → регенерирует SQL
+3. ✅ Если пароль **тот же** → использует существующий SQL
+4. ✅ Перезапускает контейнеры
+
+**Backup создается только один раз** (при первом запуске).
+
+---
+
+## 🆘 Troubleshooting
+
+### Проблема: "SYSTEM_ADMIN_USERNAME and SYSTEM_ADMIN_PASSWORD must be set!"
+
+**Решение:**
+```bash
+# Проверьте что переменные установлены в .env или production.env
+grep SYSTEM_ADMIN production.env
+
+# Должно быть:
+SYSTEM_ADMIN_USERNAME=guacadmin
+SYSTEM_ADMIN_PASSWORD=ваш_пароль
+```
+
+---
+
+### Проблема: "Python 3 not found!"
+
+**Linux/Mac:**
+```bash
+# Установите Python 3
+sudo apt install python3  # Ubuntu/Debian
+brew install python3      # macOS
+```
+
+**Windows:**
+```powershell
+# Скачайте с https://www.python.org/downloads/
+# Или установите через Winget:
+winget install Python.Python.3
+```
+
+---
+
+### Проблема: "Failed to generate SQL!"
+
+**Возможные причины:**
+
+1. ❌ Python скрипт содержит ошибки
+2. ❌ Недостаточно прав на запись файла
+3. ❌ Некорректная кодировка пароля
+
+**Решение:**
+```bash
+# Попробуйте запустить скрипт вручную:
+python3 generate_guacamole_user.py \
+  --username guacadmin \
+  --password "YourPassword" \
+  --admin \
+  --verify
+
+# Если работает - проблема в deploy.sh/deploy.ps1
+# Если не работает - проблема в скрипте или Python
+```
+
+---
+
+### Проблема: "Admin user does not exist in database"
+
+**Причины:**
+
+1. ❌ SQL не применился (PostgreSQL не запустилась)
+2. ❌ Пользователь уже существует с другим паролем
+3. ❌ Ошибка в SQL синтаксисе
+
+**Решение:**
+```bash
+# Проверьте логи PostgreSQL
+docker compose logs postgres | grep ERROR
+
+# Проверьте что SQL файл корректный
+cat 002-create-admin-user.sql
+
+# Попробуйте применить SQL вручную
+docker compose exec -T postgres psql -U guacamole_user -d guacamole_db < 002-create-admin-user.sql
+```
+
+---
+
+### Проблема: "API failed to authenticate with system credentials"
+
+**Причины:**
+
+1. ❌ Пароль в `production.env` не совпадает с паролем в БД
+2. ❌ Пользователь не существует
+3. ❌ Guacamole не запустилась
+
+**Решение:**
+```bash
+# Проверьте логи API
+docker compose logs remote_access_api | grep "System token"
+
+# Проверьте что пароли совпадают
+grep SYSTEM_ADMIN_PASSWORD production.env
+
+# Попробуйте войти в Guacamole UI с этим паролем
+# http://localhost:8080/guacamole/
+```
+
+---
+
+## 🔧 Ручной режим (без автоматики)
+
+Если хотите запустить **без автоматической генерации**:
+
+```bash
+# Используйте стандартный docker compose
+docker compose up -d
+
+# Скрипт НЕ будет запущен
+# SQL НЕ будет сгенерирован
+# Используется существующий 002-create-admin-user.sql
+```
+
+**Это полезно если:**
+- Вы уже сгенерировали SQL вручную
+- Хотите использовать дефолтный пароль (dev окружение)
+- Тестируете конфигурацию
+
+---
+
+## 📚 Дополнительные ресурсы
+
+- `QUICK_START_CUSTOM_ADMIN.md` - быстрый старт без автоматики
+- `CUSTOM_GUACAMOLE_USER.md` - ручная генерация SQL
+- `MIGRATION_SECURITY_UPDATE.md` - миграция для существующих установок
+- `generate_guacamole_user.py` - Python скрипт для генерации
+
+---
+
+## ✅ Best Practices
+
+1. ✅ **Всегда используйте безопасные пароли** (минимум 20 символов)
+2. ✅ **Генерируйте пароли случайно:** `openssl rand -base64 32`
+3. ✅ **Используйте разные пароли** для dev/staging/prod
+4. ✅ **Храните пароли безопасно** (password manager, vault)
+5. ✅ **Не коммитьте** `.env` файлы в git
+6. ✅ **Проверяйте логи** после деплоя
+7. ✅ **Делайте backup** важных файлов
+
+---
+
+**Готово! Теперь деплой безопасен и автоматизирован!** 🎉
+