<!--
  Copyright (c) 2024-2025 Тарабанов Александр Викторович
  All rights reserved.
  
  This software is proprietary and confidential.
  Unauthorized copying, modification, or distribution is prohibited.
  
  For licensing inquiries: info@hb3-accelerator.com
  Website: https://hb3-accelerator.com
  GitHub: https://github.com/HB3-ACCELERATOR
-->

# Автоматизация публикации локального приложения через SSH-туннель и NGINX

## Описание задачи

Необходимо реализовать функционал, позволяющий пользователю локального веб-приложения в один клик опубликовать своё приложение в интернете по собственному домену. Для этого используется внешний сервер (VPS) с белым IP и доменом, на котором автоматически настраиваются:
- Установка и настройка NGINX для проксирования домена на SSH-туннель
- Выпуск и установка SSL-сертификата (Let's Encrypt)
- SSH reverse-туннель с сервера на локальное приложение пользователя
- (Опционально) Автоматическая установка NGINX и certbot на сервере по SSH силами локального агента

Пользователь заполняет форму с необходимыми данными, после чего система автоматически выполняет все шаги по настройке инфраструктуры.

---

## Архитектура решения

1. **Локальное приложение** работает в Docker-контейнере на ПК пользователя (порт 5173 проброшен наружу).
2. **Локальный агент** (Node.js-приложение) устанавливается на ПК пользователя и позволяет фронтенду запускать команды (например, поднять SSH-туннель, а также настраивать NGINX/SSL на сервере по SSH) в один клик.
3. **Агент по SSH подключается к серверу (VPS)** и:
   - Устанавливает NGINX и certbot (если не установлены)
   - Создаёт или обновляет конфиг NGINX для указанного домена (проксирует на порт 9000)
   - Перезапускает NGINX
   - Выпускает SSL-сертификат через certbot
   - Проверяет доступность домена по HTTPS
   - Запускает SSH reverse-туннель (9000:localhost:5173)
4. **NGINX** на сервере проксирует домен на порт туннеля (9000).

---

## Необходимые данные для формы

- Домен (например, myapp.example.com)
- Host/IP сервера
- Пользователь SSH
- SSH-ключ (или пароль)
- E-mail для SSL (Let's Encrypt)

**Поля "Локальный порт приложения", "Порт на сервере для туннеля" и "Порт SSH" скрыты и всегда используются значения по умолчанию:**
- Локальный порт: 5173
- Порт на сервере: 9000
- Порт SSH: 22

---

## UX-поток с локальным агентом (финальный порядок)

1. Пользователь заходит в локальное веб-приложение и заполняет форму публикации (домен, SSH и т.д.).
2. Нажимает кнопку "Опубликовать".
3. Агент автоматически скачивается, устанавливается и запускается (без дополнительных действий пользователя).
4. После запуска агента фронтенд отправляет параметры публикации на локальный агент (порты и порт SSH подставляются автоматически).
5. Агент по SSH подключается к серверу и:
   - Устанавливает NGINX и certbot (если не установлены)
   - Создаёт или обновляет конфиг NGINX для домена
   - Перезапускает NGINX
   - Выпускает SSL-сертификат через certbot
   - Запускает SSH reverse-туннель (9000:localhost:5173, порт SSH всегда 22)
6. После успешного запуска туннеля приложение становится доступно по домену из интернета.

---

## План выполнения

### 1. Фронтенд
- [ ] Добавить на страницу настроек интерфейса блок "WEB SSH" с кнопкой "Подробнее"
- [ ] Создать отдельную страницу
- [ ] Реализовать отправку формы на локальный агент (поля с портами и портом SSH скрыты, используются значения по умолчанию)
- [ ] После успешной настройки — отобразить пользователю статус публикации с ссылкой на домен

### 2. Локальный агент
- [ ] Реализовать Node.js-приложение (Web SSH Agent), слушающее локальный порт
- [ ] API: запуск/остановка SSH-туннеля, статус, логирование
- [ ] Автоматическая установка и настройка NGINX, выпуск SSL-сертификата на сервере по SSH
- [ ] Безопасность: принимать команды только с localhost, авторизация по токену
- [ ] Инструкция по установке для пользователя (Windows, Mac, Linux)
- [ ] (Опционально) Автообновление агента

### 3. Бэкенд (опционально)
- [ ] Реализовать API для логирования, аудита, хранения истории публикаций (если требуется)
- [ ] Возвращать статус выполнения и сообщения об ошибках (если используется)

### 4. Инфраструктура/DevOps
- [ ] Проверить, что на сервере открыт порт 9000 для туннеля
- [ ] Проверить, что домен указывает на сервер
- [ ] Проверить, что на сервере установлен NGINX и certbot
- [ ] (Опционально) Добавить systemd unit для автозапуска туннеля

---

## Важные замечания
- Для полной автоматизации публикации в один клик требуется локальный агент, который запускает команды на ПК пользователя и может настраивать сервер по SSH.
- В браузере без агента можно только сгенерировать команду для ручного запуска SSH-туннеля.
- Все действия на сервере должны выполняться только для авторизованных пользователей (лучше — только для админов)
- Необходимо реализовать валидацию всех полей формы
- **Используется именно проброшенный наружу порт из Docker (5173)**
- **Порт SSH всегда 1024 (по умолчанию), пользователь не видит это поле**

---

приложение остаётся локально — туннель обязателен

---

## Пример команды для SSH-туннеля

```bash
ssh -i /path/to/key -p 22 -R 9000:localhost:5173 user@ваш-сервер
```

---

## С локальным агентом публикация действительно становится "в один клик"! 