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

⚡ Быстрый старт: Кастомный администратор Guacamole

🎯 Цель

Развернуть проект с безопасным паролем администратора с самого начала.

Время выполнения: 5 минут

---

📋 Шаг 1: Генерируем безопасный пароль

# 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 для администратора

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

# Делаем 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

nano production.env

Установите те же credentials:

# System Admin Account
SYSTEM_ADMIN_USERNAME=guacadmin
SYSTEM_ADMIN_PASSWORD=YOUR_SECURE_PASSWORD  # ⬅️ Тот же пароль!

⚠️ КРИТИЧНО: Пароли ДОЛЖНЫ совпадать!

---

📋 Шаг 5: Первый запуск

# Запускаем проект
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: Проверяем доступ

# Проверяем вход в 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:

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

Решение:

# Проверяем что пароли совпадают
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:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
python generate_guacamole_user.py --username admin --password "Pass123!"

---

Проблема: SQL не применяется автоматически

Причина: SQL скрипты в docker-entrypoint-initdb.d выполняются только если БД пустая.

Решение для существующей БД:

# Применить вручную
docker compose exec -T postgres psql -U guacamole_user -d guacamole_db < 002-create-admin-user.sql

Решение для чистой установки:

# Удалить volume и пересоздать
docker compose down -v
docker compose up -d

---

📊 Проверка корректности хеша

Скрипт имеет встроенную проверку с флагом --verify:

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 - переменные окружения

---

Готово! Теперь ваш проект защищен с самого начала! 🎉