init_guac

guacamole_test_11_26/docs/QUICK_START_CUSTOM_ADMIN.md

@@ -0,0 +1,262 @@
+# ⚡ Быстрый старт: Кастомный администратор Guacamole
+
+## 🎯 Цель
+
+Развернуть проект с **безопасным паролем администратора** с самого начала.
+
+**Время выполнения:** 5 минут
+
+---
+
+## 📋 Шаг 1: Генерируем безопасный пароль
+
+```bash
+# Windows PowerShell
+$password = -join ((65..90) + (97..122) + (48..57) + (33,35,36,37,38,42,43,45,61) | Get-Random -Count 20 | ForEach-Object {[char]$_})
+echo "Generated password: $password"
+
+# Linux/Mac
+openssl rand -base64 32
+```
+
+**Сохраните пароль в безопасное место** (password manager)!
+
+---
+
+## 📋 Шаг 2: Генерируем SQL для администратора
+
+```bash
+cd GuacamoleRemoteAccess
+
+# Замените YOUR_SECURE_PASSWORD на сгенерированный пароль
+python generate_guacamole_user.py \
+  --username guacadmin \
+  --password "YOUR_SECURE_PASSWORD" \
+  --admin \
+  --verify \
+  > 002-create-admin-user-custom.sql
+```
+
+**Пример вывода:**
+```
+[VERIFY] Verifying hash generation...
+[OK] Hash generation verified
+[OK] SQL generated successfully!
+   Username: guacadmin
+   Role: Administrator
+   Password length: 20 characters
+```
+
+---
+
+## 📋 Шаг 3: Заменяем дефолтный SQL
+
+```bash
+# Делаем backup оригинала
+mv 002-create-admin-user.sql 002-create-admin-user-DEFAULT-BACKUP.sql
+
+# Используем наш кастомный
+mv 002-create-admin-user-custom.sql 002-create-admin-user.sql
+```
+
+**Теперь при первом запуске будет использован ВАШ пароль!**
+
+---
+
+## 📋 Шаг 4: Обновляем production.env
+
+```bash
+nano production.env
+```
+
+**Установите те же credentials:**
+```bash
+# System Admin Account
+SYSTEM_ADMIN_USERNAME=guacadmin
+SYSTEM_ADMIN_PASSWORD=YOUR_SECURE_PASSWORD  # ⬅️ Тот же пароль!
+```
+
+⚠️ **КРИТИЧНО:** Пароли ДОЛЖНЫ совпадать!
+
+---
+
+## 📋 Шаг 5: Первый запуск
+
+```bash
+# Запускаем проект
+docker compose up -d
+
+# Проверяем логи
+docker compose logs postgres | grep "guacadmin"
+docker compose logs remote_access_api | grep "System token"
+```
+
+**Ожидаемый результат:**
+```
+[OK] System token refreshed successfully
+[OK] Application startup complete
+```
+
+---
+
+## 📋 Шаг 6: Проверяем доступ
+
+```bash
+# Проверяем вход в Guacamole UI
+# Откройте: https://mc.exbytestudios.com
+# Войдите: guacadmin / YOUR_SECURE_PASSWORD
+
+# Проверяем API
+curl -X POST https://mc.exbytestudios.com/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "guacadmin", "password": "YOUR_SECURE_PASSWORD"}'
+```
+
+**Должны получить JWT токен!**
+
+---
+
+## ✅ Checklist
+
+- [ ] Сгенерирован безопасный пароль (минимум 16 символов)
+- [ ] SQL создан через `generate_guacamole_user.py`
+- [ ] Оригинальный `002-create-admin-user.sql` заменен
+- [ ] `production.env` обновлен с теми же credentials
+- [ ] Проект запущен (`docker compose up -d`)
+- [ ] Логи подтверждают успешный старт
+- [ ] Можно войти в Guacamole UI с новым паролем
+- [ ] API возвращает JWT токен
+- [ ] Backup оригинального SQL сохранен (опционально)
+
+---
+
+## 🔄 Альтернативный вариант: Для существующей установки
+
+Если проект уже запущен и нужно **изменить** пароль guacadmin:
+
+```bash
+# 1. Генерируем новый хеш
+python generate_guacamole_user.py \
+  --username guacadmin \
+  --password "NEW_SECURE_PASSWORD" \
+  --admin \
+  > update-admin-password.sql
+
+# 2. Редактируем SQL для UPDATE вместо INSERT
+# Меняем INSERT на UPDATE (см. CUSTOM_GUACAMOLE_USER.md)
+
+# 3. Применяем к существующей БД
+docker compose exec -T postgres psql -U guacamole_user -d guacamole_db < update-admin-password.sql
+
+# 4. Обновляем production.env
+nano production.env
+# SYSTEM_ADMIN_PASSWORD=NEW_SECURE_PASSWORD
+
+# 5. Перезапускаем API
+docker compose restart remote_access_api
+```
+
+---
+
+## 🆘 Troubleshooting
+
+### Проблема: "Failed to authenticate system user"
+
+**Решение:**
+```bash
+# Проверяем что пароли совпадают
+docker compose exec postgres psql -U guacamole_user -d guacamole_db -c \
+  "SELECT name FROM guacamole_user u 
+   JOIN guacamole_entity e ON u.entity_id = e.entity_id 
+   WHERE e.name = 'guacadmin';"
+
+# Если пользователь существует - проверьте пароль в production.env
+grep SYSTEM_ADMIN_PASSWORD production.env
+```
+
+---
+
+### Проблема: Скрипт выдает ошибку кодировки
+
+**Решение:** Используйте PowerShell с UTF-8:
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+python generate_guacamole_user.py --username admin --password "Pass123!"
+```
+
+---
+
+### Проблема: SQL не применяется автоматически
+
+**Причина:** SQL скрипты в `docker-entrypoint-initdb.d` выполняются **только если БД пустая**.
+
+**Решение для существующей БД:**
+```bash
+# Применить вручную
+docker compose exec -T postgres psql -U guacamole_user -d guacamole_db < 002-create-admin-user.sql
+```
+
+**Решение для чистой установки:**
+```bash
+# Удалить volume и пересоздать
+docker compose down -v
+docker compose up -d
+```
+
+---
+
+## 📊 Проверка корректности хеша
+
+Скрипт имеет встроенную проверку с флагом `--verify`:
+
+```bash
+python generate_guacamole_user.py \
+  --username test \
+  --password "TestPass123" \
+  --verify
+```
+
+**Вывод:**
+```
+[VERIFY] Verifying hash generation...
+[OK] Hash generation verified
+```
+
+Это гарантирует что:
+- ✅ Salt генерируется случайно (каждый раз разный)
+- ✅ Hash вычисляется корректно (SHA-256)
+- ✅ Формат совместим с Guacamole
+
+---
+
+## 🔐 Безопасность
+
+**Рекомендации:**
+
+1. ✅ **Генерируйте пароли случайно** (минимум 20 символов)
+2. ✅ **Не используйте дефолтные пароли** (`guacadmin:guacadmin`)
+3. ✅ **Не коммитьте** `.env` файлы и SQL с паролями в git
+4. ✅ **Храните пароли безопасно** (password manager, vault)
+5. ✅ **Меняйте пароли регулярно** (каждые 90 дней)
+6. ✅ **Используйте `--verify`** для проверки корректности
+
+**Что НЕ делать:**
+
+- ❌ Не используйте простые пароли (`admin123`, `password`)
+- ❌ Не храните пароли в plain text в git
+- ❌ Не используйте один и тот же пароль для разных окружений
+- ❌ Не давайте системные credentials обычным пользователям
+
+---
+
+## 📚 Дополнительные материалы
+
+- `CUSTOM_GUACAMOLE_USER.md` - полное руководство
+- `MIGRATION_SECURITY_UPDATE.md` - миграция для существующих установок
+- `DEPLOYMENT_API_GUIDE.md` - деплой проекта
+- `production.env` - переменные окружения
+
+---
+
+**Готово!** Теперь ваш проект защищен с самого начала! 🎉
+