# VPN Telegram Bot + Remnawave Panel

Telegram-бот для выдачи VPN-подписок через API панели **Remnawave**.

Деплой: **Docker Compose** на Ubuntu (22.04 / 24.04 LTS).

Сейчас контейнер запускает проверку API (`check_api.py`). Дальше — `bot.py`.

---

## Содержание

1. [Что понадобится](#1-что-понадобится)
2. [Токен API в Remnawave](#2-токен-api-в-remnawave)
3. [Установка Docker на Ubuntu](#3-установка-docker-на-ubuntu)
4. [Установка проекта](#4-установка-проекта)
5. [Настройка `.env`](#5-настройка-env)
6. [Сборка и проверка API](#6-сборка-и-проверка-api)
7. [Структура проекта](#7-структура-проекта)
8. [Постоянный запуск бота](#8-постоянный-запуск-бота)
9. [Полезные команды](#9-полезные-команды)
10. [Частые ошибки](#10-частые-ошибки)
11. [Что дальше](#11-что-дальше)

---

## 1. Что понадобится

| Компонент | Зачем |
|-----------|--------|
| VPS / сервер Ubuntu 22.04 или 24.04 | Где крутится Docker |
| Docker + Docker Compose plugin | Сборка и запуск контейнера |
| Доступ к панели Remnawave | URL, например `https://panel.example.com` |
| API Token из панели | Авторизация запросов к API |
| [@BotFather](https://t.me/BotFather) | `BOT_TOKEN` (на следующем этапе) |

Официальные материалы Remnawave:

- Панель: [https://remna.st](https://remna.st)
- Python SDK: [https://github.com/remnawave/python-sdk](https://github.com/remnawave/python-sdk)

---

## 2. Токен API в Remnawave

1. Открой панель (например `https://panel.example.com`).
2. Войди под админом.
3. **Settings → API Tokens** — создай токен.
4. Скопируй сразу и положи в `.env` на сервере.

Если Caddy режет API отдельным ключом — понадобится ещё `CADDY_TOKEN`.

---

## 3. Установка Docker на Ubuntu

Подключись по SSH:

```bash
ssh user@your-server-ip
```

### Официальный способ (рекомендуется)

```bash
sudo apt update
sudo apt install -y ca-certificates curl

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

Проверка:

```bash
docker --version
docker compose version
sudo docker run --rm hello-world
```

Чтобы не писать `sudo` каждый раз:

```bash
sudo usermod -aG docker "$USER"
# выйди из SSH и зайди снова
newgrp docker
docker run --rm hello-world
```

### Быстрый вариант (snap, если так удобнее)

```bash
sudo snap install docker
docker --version
```

На production обычно лучше пакеты с `download.docker.com`, как выше.

---

## 4. Установка проекта

### 4.0. Установщик в 1 команду (рекомендуется)

На чистом Ubuntu 22.04 / 24.04, в каталоге с кодом:

```bash
sudo bash install.sh
```

Скрипт спросит домен, Remnawave, `BOT_TOKEN`, Postgres, логин админки, SMTP (опционально), поставит Docker при необходимости, откроет 80/443 (UFW), запишет `.env`, поднимет **Postgres + бот + Caddy (Let's Encrypt SSL)**.

Полезные флаги:

```bash
sudo bash install.sh --help
sudo bash install.sh --reinstall   # пересборка без опроса (.env уже есть)
sudo bash install.sh --env-only    # только пересоздать .env
```

### 4.1. Положи код на сервер

```bash
sudo mkdir -p /opt/vpn-telegram-bot
sudo chown "$USER":"$USER" /opt/vpn-telegram-bot
cd /opt/vpn-telegram-bot
```

Через git:

```bash
git clone <URL_РЕПОЗИТОРИЯ> .
```

Или с локальной машины:

```bash
scp -r ./vpn-telegram-bot/* user@your-server-ip:/opt/vpn-telegram-bot/
```

В каталоге должны быть как минимум:

- `Dockerfile`
- `docker-compose.yml`
- `requirements.txt`
- `check_api.py`
- `config.py`
- `remnawave_client.py`
- `.env.example`

### 4.2. Docker Compose не ставит Python на хост

Python и зависимости живут **внутри образа**. На хосте нужен только Docker.

---

## 5. Настройка `.env`

```bash
cd /opt/vpn-telegram-bot
cp .env.example .env
nano .env
chmod 600 .env
```

Пример:

```env
REMNAWAVE_BASE_URL=https://panel.example.com
REMNAWAVE_TOKEN=вставь_сюда_токен_панели

# Токен Telegram-бота от @BotFather
BOT_TOKEN=123456:AA...

# ID админов через запятую
ADMIN_IDS=123456789

# CADDY_TOKEN=
```

Правила:

- `REMNAWAVE_BASE_URL` — без `/` в конце, обычно без `/api`.
- `REMNAWAVE_TOKEN` — без слова `Bearer`.
- `BOT_TOKEN` — токен от [@BotFather](https://t.me/BotFather) (`/newbot`).
- `.env` не коммитить (есть в `.gitignore` и `.dockerignore`).

Compose подхватывает `.env` через `env_file` и подставляет переменные в контейнер.

---

## 6. Сборка и проверка API

Из каталога проекта:

```bash
cd /opt/vpn-telegram-bot

# собрать образ
docker compose build

# одноразовый прогон проверки API
docker compose run --rm bot
```

Или явно:

```bash
docker compose run --rm bot python check_api.py
```

Успех — в логе что-то вроде:

```text
✓ Remnawave API принимает запросы. Можно продолжать бота.
```

С verbose:

```bash
docker compose run --rm bot python check_api.py --verbose
```

Пересобрать после смены кода:

```bash
docker compose build --no-cache
```

---

## 7. Структура проекта

```text
vpn-telegram-bot/
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── .env                 # секреты (не в git / не в образ)
├── .env.example
├── .gitignore
├── requirements.txt
├── config.py
├── remnawave_client.py
├── check_api.py
└── README.md
```

| Файл | Роль |
|------|------|
| `Dockerfile` | Образ Python 3.12 + зависимости |
| `docker-compose.yml` | Сервис `bot`, env, command |
| `check_api.py` | Проверка, что Remnawave API принимает запросы |

---

## 8. Запуск бота

`bot.py` отвечает на `/start` приветствием.

```bash
docker compose up -d --build
docker compose ps
docker compose logs -f bot
```

В Telegram открой бота и нажми **Start** (или отправь `/start`).

Остановить:

```bash
docker compose down
```

Проверка API по-прежнему:

```bash
docker compose run --rm bot python check_api.py
```

---

## 9. Полезные команды

```bash
# статус
docker compose ps

# логи
docker compose logs -f bot

# перезапуск
docker compose restart bot

# войти в контейнер
docker compose run --rm --entrypoint sh bot

# проверить сеть до панели с хоста
curl -sS -o /dev/null -w "%{http_code}\n" https://panel.example.com/api/system/health

# проверить из контейнера
docker compose run --rm bot curl -sS -o /dev/null -w "%{http_code}\n" https://panel.example.com/api/system/health
```

---

## 10. Частые ошибки

### `REMNAWAVE_TOKEN не задан`

Пустой `.env` или compose запущен не из каталога с `.env`.

```bash
cd /opt/vpn-telegram-bot
grep REMNAWAVE_ .env
docker compose run --rm bot env | grep REMNAWAVE_
```

### `401` / токен не принят

Неверный или отозванный токен, лишние пробелы/переносы в `.env`.

После правки `.env` перезапускать контейнер:

```bash
docker compose run --rm bot python check_api.py
```

### Не собирается образ / нет Docker

```bash
docker compose version
sudo systemctl status docker
sudo systemctl enable --now docker
```

### Сеть из контейнера

Если с хоста панель открывается, а из контейнера нет — DNS/firewall Docker:

```bash
docker compose run --rm bot curl -vI https://panel.example.com
```

### Permission denied на docker.sock

Пользователь не в группе `docker` — см. раздел 3 (`usermod -aG docker`).

### Caddy auth

Раскомментируй `CADDY_TOKEN` в `.env`.

---

## 11. Что дальше

1. Убедиться, что `docker compose run --rm bot` проходит проверку API.
2. Добавить `BOT_TOKEN` в `.env`.
3. Написать `bot.py` (aiogram) и сменить `command` / `restart` в compose.
4. Поднять постоянно: `docker compose up -d --build`.

---

## Краткая шпаргалка (Ubuntu + Docker Compose)

```bash
# Docker (один раз)
sudo apt update
# ... установка docker-ce и docker-compose-plugin из раздела 3 ...

# Проект
cd /opt/vpn-telegram-bot
cp .env.example .env
nano .env          # REMNAWAVE_BASE_URL + REMNAWAVE_TOKEN
chmod 600 .env

docker compose build
docker compose run --rm bot
```

Если проверка прошла — можно переходить к Telegram-боту в том же Compose.