# ⚡ Быстрый старт: Кастомный администратор 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` - переменные окружения

---

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