Remote-Control-Center/guacamole_test_11_26/docs/AUTO_DEPLOY_GUIDE.md

🚀 Автоматический деплой с безопасным администратором

🎯 Что делает автоматический деплой?

При запуске 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:

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):

cd GuacamoleRemoteAccess

# 1. Обновите production.env с безопасным паролем
notepad production.env
# SYSTEM_ADMIN_USERNAME=guacadmin
# SYSTEM_ADMIN_PASSWORD=YourSecurePassword123!

# 2. Запустите deploy скрипт
.\deploy.ps1

Вот и всё! Скрипт сделает остальное.

---

📊 Пример работы скрипта

$ ./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

---

🔐 Проверка безопасности

Скрипт автоматически проверяет небезопасные пароли:

❌ Будет предупреждение:

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):

✅ Будет генерация:

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 - после генерации содержит ваш пароль (не коммитится!)

Если нужно восстановить оригинал:

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!"

Решение:

# Проверьте что переменные установлены в .env или production.env
grep SYSTEM_ADMIN production.env

# Должно быть:
SYSTEM_ADMIN_USERNAME=guacadmin
SYSTEM_ADMIN_PASSWORD=ваш_пароль

---

Проблема: "Python 3 not found!"

Linux/Mac:

# Установите Python 3
sudo apt install python3  # Ubuntu/Debian
brew install python3      # macOS

Windows:

# Скачайте с https://www.python.org/downloads/
# Или установите через Winget:
winget install Python.Python.3

---

Проблема: "Failed to generate SQL!"

Возможные причины:

1. ❌ Python скрипт содержит ошибки
2. ❌ Недостаточно прав на запись файла
3. ❌ Некорректная кодировка пароля

Решение:

# Попробуйте запустить скрипт вручную:
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 синтаксисе

Решение:

# Проверьте логи 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 не запустилась

Решение:

# Проверьте логи API
docker compose logs remote_access_api | grep "System token"

# Проверьте что пароли совпадают
grep SYSTEM_ADMIN_PASSWORD production.env

# Попробуйте войти в Guacamole UI с этим паролем
# http://localhost:8080/guacamole/

---

🔧 Ручной режим (без автоматики)

Если хотите запустить без автоматической генерации:

# Используйте стандартный 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 важных файлов

---

Готово! Теперь деплой безопасен и автоматизирован! 🎉