Подключить сервер

Add Server Wizard — официальный путь подключения RoqueOS фронтенда (на https://roqueos.com.br/app) к вашему RoqueOS Server. Находится в Settings → Server → Добавить сервер.

Заменяет старый flow, который просил пользователя открыть <server>:27021/admin в браузере. Теперь всё происходит внутри приложения.

Когда использовать

• ✅ Только что установленный сервер (install.sh запущен, API Keys ещё нет) — wizard создаёт первый admin key
• ✅ Сервер уже используется (у вас сохранены apiKey + apiSecret) — wizard валидирует и добавляет в список
• ✅ Сменить сервер — добавить второй сервер, переключаться между ними через Switcher в menubar

Bootstrap flow (пустой сервер)

7 шагов. Общее время: ~1 мин.

Step 1 — URL

Вставьте URL сервера. Принимает:

• http://localhost:27021 (Docker работает на вашей машине — работает через loopback)
• https://server.example.com (за Cloudflare Tunnel или TLS сертификатом)

Wizard нормализует протокол (server.example.com → https://server.example.com автоматически) и обнаруживает уже зарегистрированные серверы прежде чем продолжить.

⚠️ HTTP vs HTTPS — ограничение браузера

Фронтенд roqueos.com.br/app работает в HTTPS. По дизайну современных браузеров (Mixed Content policy), HTTPS-страница НЕ может вызывать HTTP API — браузер тихо блокирует request даже до того как он покинет машину.

Это значит, что попытка подключить http://192.168.1.50:27021 (LAN) или http://server.com:27021 (публичный) провалится с "couldn't connect" что выглядит как баг сервера, но это блокировка браузера.

Wizard обнаруживает это для вас и показывает жёлтый баннер объясняющий проблему до того как request пройдёт. Три решения, в порядке предпочтения:

1. HTTPS через Cloudflare Tunnel (рекомендовано)

Бесплатно, plug-and-play. install.sh уже имеет встроенную поддержку:

curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update
# Потом: Settings → Server → Cloudflare Tunnel → Подключить

Результат: ваш сервер находится на https://<id>.cloud.roqueos.com.br или вашем собственном домене. Автоматический TLS, не лезть в firewall, не нужен публичный IP.

Полный install.sh + Cloudflare Tunnel гайд →

2. Используйте десктоп или мобильное приложение

Нативные wrappers (Microsoft Store, Play Store, App Store) не имеют ограничения mixed content — они запускают нативный код, не web-страницы в строгом HTTPS.

• 🪟 Microsoft Store (Windows)
• 🍎 App Store (iOS/macOS)
• 🤖 Google Play (Android)

Хорошо для: homelab окружения где вы не хотите/не можете настроить tunnel.

3. Сервер на localhost (loopback)

http://localhost:27021, http://127.0.0.1:27021 и http://[::1]:27021 рассматриваются как безопасный контекст современными браузерами через Secure Contexts spec — поэтому работают даже с HTTPS фронтендом.

Хорошо для: локальной разработки, тестирования перед заливкой на реальный сервер.

Step 2 — Detect

Wizard хитит 2 анонимных endpoint параллельно:

• GET /health/version-info — версия + minClientVersion
• GET /admin/setup — если возвращает { needsSetup: true }, сервер пустой

Здесь также проверяет compat версий. Если сервер на v1.0.10 но клиент (фронтенд) требует v1.0.13+, показывает дружелюбное предупреждение "сначала обновите сервер" + ссылку на install.sh --update.

Step 3 — Bootstrap (пустой сервер)

Кнопка "Создать admin key" → POST /admin/setup (rate-limited по IP на сервере чтобы избежать setup race).

Возвращает { apiKey, apiSecret } который wizard отображает на следующем шаге.

Обработка race: если 2 браузера пытаются setup одновременно, второй получает error: 'Setup already completed' и wizard переходит на step 5 (manual credentials).

Step 4 — keyCreated

Показывает возвращённые apiKey + apiSecret в read-only полях с кнопкой copy.

⚠️ Критический UX guard:

• Модал имеет closeOnBackdrop=false (не закрывается кликом снаружи)
• Кнопка X открывает sub-модал подтверждения ("Вы сохранили credentials?")
• Обязательный чекбокс "Я сохранил мои credentials" включает кнопку Next
• Если закроете не сохранив, key остаётся на сервере но потерян для вас — recovery только через /admin HTML legacy

Step 5 — credentials (сервер уже настроен)

Если на step 2 обнаружение указало что setup уже был сделан, прыгает сразу сюда:

• Поле apiKey
• Поле apiSecret
• Ссылка "Открыть admin панель сервера ↗" (открывает <server>/admin HTML legacy в новой вкладке)

Legacy страница продолжает быть бэкдором для recovery и автоматизации.

Step 6 — Имя

Единственное поле: дружественное имя сервера (появляется в Server Switcher menubar).

Предложенное по умолчанию: URL.hostname (например: demo.level-hard.com или localhost).

Step 7 — Finalize

Wizard вызывает:

• addBackendService({ name, url }) — сохраняет в списке backendSettings.services
• setApiCredentials(apiKey, apiSecret, serviceId) — хранит creds в Firestore
• setActiveBackendService(serviceId) — делает активным

Модал закрывается. Сервер подключён. Вы в Server Mode.

Server Switcher (menubar)

Когда у вас 2+ серверов зарегистрировано, появляется dropdown в menubar (верхний левый угол) показывающий активный сервер. Click чтобы переключиться между ними.

Текущий статус (май 2026): компонент ROSServerSwitcher ещё не пересобран после предыдущей сессии — фича запланирована но не выпущена. Пока что переключение между серверами через Settings → Server → клик на нужном сервере.

Публичный демо-сервер

Чтобы протестировать Server Mode без установки чего-либо на вашу машину, RoqueOS уже идёт с публичным предварительно настроенным демо-сервером:

1. Залогиньтесь на https://roqueos.com.br/app
2. Перейдите в Settings → Server
3. DEMO сервер уже появляется в списке — click чтобы активировать

Не нужно вставлять URL, apiKey или apiSecret — credentials встроены в клиент и работают напрямую.

Что такое демо: настоящий instance RoqueOS Server, обновляемый основателем, с ежедневной очисткой (осиротевшие контейнеры, agents/sessions > 24h, висящие тома). Лимиты:

• Не-admin не видит Server Admin Panel (security gate)
• Cloud Gaming может purge zombie session
• Контейнеры остаются ~24h до prune
• Расшарен между всеми посетителями

Хорошо для: исследовать Containers, Terminal, встроенный VS Code, Files. Плохо для: долговременной персистентности, чувствительных или важных данных — любой залогиненный в RoqueOS может использовать тот же демо параллельно.

Для реального использования установите свой сервер через one-liner.

Устранение неполадок

Симптом	Решение
"Сервер недоступен"	Подтвердите curl <url>/health возвращает 200. Возможно порт 27021 не открыт или Docker остановлен
"Сервер уже зарегистрирован"	Wizard обнаружил дубликат. Перейдите в Settings → Server и выберите существующий
"Сервер устарел"	Запустите --update на сервере: curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update
"Setup already completed" но вы никогда не настраивали	Reset: docker exec roqueos-server sqlite3 /app/data/roqueos.db "DELETE FROM api_keys;" (осторожно — удаляет все существующие keys)
Сервер добавился но Settings возвращает пустым	Возможно не хватило Firestore логина. Проверьте в DevTools console появляется ли Firestore: PERMISSION_DENIED

Ссылки

• install.sh one-liner — чтобы поднять сервер заранее
• Server Admin Panel — управлять после подключения
• Volumes & бэкап — понять персистентность
• Внутренний Composable: src/composables/useAddServerWizard.js (state + flow)