---
icon: material/upload-network
tags: ["iptvc", "docker", "deploy", "nginx", "apache", "ssl"]
---

# :material-upload-network: Развёртывание сайта

В этом разделе описан фактический порядок настройки `iptvc`, хранилищем KeyDB и документацией.

## :material-flag-checkered: Базовый вариант развёртывания сервиса { id="local" }

Для запуска приложения не нужен репозиторий с исходниками.
Достаточно [скачать актуальный релиз](../install.md) для своей платформы.

Чтобы запустить его, достаточно расположить его в любой удобной директории на диске и выполнить команду:

```shell
./iptvc serve
```

Откройте в браузере адрес <http://localhost:8800/> и убедитесь в работе сервиса.

Вы должны увидеть ошибку:

```
Не удалось загрузить список плейлистов. Проверьте наличие файла playlists.ini.
```

Всё верно.
Для полноценной работы приложения в качестве веб-сервиса следует провести минимальные настройки.

### Список плейлистов — `playlists.ini` { id="playlists" }

!!! info "Синтаксис описан в [этом разделе документации](../../ref/formats/playlists.md)"

Без этого файла нет смысла запускать веб-сервис.

Файл можно положить рядом с `iptvc`.

Как только вы подготовите файл, перезапустите сервис командой выше.
Вы должны увидеть список плейлистов на главной странице.

Но все они будут серого цвета и будет доступна только базовая информация о них.
Зато будут работать короткие ссылки и их уже можно будет казывать в своём любимом [плеере](../../ref/players.md).

Чтобы плейлисты позеленели, нужно запустить приложение в режиме активной проверки плейлистов:

```shell
./iptvc serve --check
```

!!! tip "У этой команды есть и другие аргументы"
    Полный список указан здесь: [**Команда `serve`**](../commands/serve.md).
    Они позволят, при необходимости, очень гибко настроить параметры сайта и режима проверки.

### Список правил — `channels.json` { id="channels" }

!!! info "Синтаксис описан в [этом разделе документации](../../ref/formats/channels.md)"

Без этого файла можно жить: веб-сервис будет работать, плейлисты и каналы будут проверяться, короткие ссылки в вашем распоряжении.

Но **все** каналы будут помечены как `#untagged`.
Это значит, что такие каналы можно будет искать только по названиям.
Поиск по жанрам и странам будет недоступен.

Это может быть важно для разных пользователей.

Поэтому варианта здесь три:

1. продолжать пользоваться сервисом как есть;
2. подготовить свой файл `channels.json` согласно его правил синтаксиса;
3. скачать готовый файл из репозитория: [channels.json](https://git.axenov.dev/IPTV/iptvc/raw/branch/master/channels.json)

??? tip "Рекомендуется третий вариант"
    Файл в репозитории периодически обновляется по тем плейлистам, которые широко распространяются в сети.
    В нём собраны правла для многих телеканалов СНГ и Европы.
    Хотя и далеко не все.
    Поэтому, если вы умеете работать с регулярными выражениями, вы можете предложить свои правила в репозиторий.

Файл можно положить туда же — рядом с `iptvc`.

Когда файл будет готов, перезапустите приложение предыдущей командой.

Поздравляю, теперь у вас свой собственный рабочий агрегатор плейлистов.
Вы можете его использовать в домашней сети или на своём ПК — для мониторинга состояния плейлистов или для просмотра.

### Конфигурация приложения — `config.yml`

!!! info "Синтаксис описан в [этом разделе документации](../../ref/config.md)"

Теперь можете приступить к конфигурации приложения.

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

Файл можно положить туда же — рядом с `iptvc`.

Но постойте.
Вы уже несколько раз перезапустили приложение, а результаты проверки плейлистов сбрасываются.
А если вы перезагрузите компьютер, то придётся заново вручную запускать приложение.

Давайте это исправим в следующих шагах.

## :simple-docker: Развёртывание через Docker { id="docker" }

Установка docker осуществляется согласно официальной документации.

??? tip "Для MacOS вместо Docker Desktop рекомендую [OrbStack](https://orbstack.dev)"
    Он быстрый, лёгкий, бесплатный и не жрёт столько ресурсов, как официальное приложение.
    В общем-то, сама по себе гуйня для докера бесполезна и не нужна, но на маке эта тулза поможет с запуском докера на сокете в пространстве текущего пользователя.
    К сожалению, иначе на маке докер работать в фоне не может из-за политик безопасности.
    Либо может, но это потребует кучу гемора на ровном месте.

Для этого нужно будет скачать ещё один файл из репозитория: [compose.yml](https://git.axenov.dev/IPTV/iptvc/raw/branch/master/compose.yml)



---

---

---



## Подготовка репозитория { id="repository" }

Клонируйте основной репозиторий и перейдите в его каталог:

```bash
git clone https://git.axenov.dev/IPTV/.git
cd IPTV
```

В корне проекта должны находиться `compose.yml`, `.env`, `config.yml`, `playlists.ini`, `channels.json` и каталог `docker/keydb`.

Исходный код приложения располагается в `iptvc/`, а документации — в `docs/`.

## Настройка файлов { id="configuration" }

Создайте файлы локальной конфигурации на основе примеров:

```bash
cp .env.example .env
cp iptvc/config.yml.example config.yml
```

Отредактируйте `config.yml`.

В контейнере `iptvc` он подключается как `/app/config.yml`.

Минимально проверьте следующие параметры:

- `app.playlists` — путь к файлу плейлистов;
- `app.tags` — путь к файлу тегов каналов;
- `server.host` и `server.port` — адрес и порт веб-интерфейса;
- `cache.enabled` и параметры `cache` — использование KeyDB;
- `site.base-url` — внешний адрес приложения.

Скопируйте входные данные плейлистов в корень окружения:

```bash
cp /path/to/playlists.ini ./playlists.ini
cp /path/to/channels.json ./channels.json
```

Эти файлы монтируются в контейнер как `/app/playlists.ini` и `/app/channels.json`.

В `.env` задаются параметры приложения из `iptvc/.env.example`, включая `SITE_BASE_URL`, `SERVER_PORT`, `CACHE_ENABLED`, `CACHE_HOST`, `CACHE_PORT`, `CACHE_DB` и `CACHE_TTL`.

Для подключения к KeyDB из контейнера укажите имя сервиса `keydb` в `CACHE_HOST`, а не `localhost`.

## Состав окружения { id="services" }

Файл `compose.yml` запускает три сервиса:

| Сервис  | Образ                                  | Назначение                                  |
| ------- | -------------------------------------- | ------------------------------------------- |
| `iptvc` | `git.axenov.dev/iptv/iptvc:latest`     | Веб-интерфейс и фоновая проверка плейлистов |
| `keydb` | `eqalpha/keydb:latest`                 | Кеш результатов проверки                    |
| `docs`  | `git.axenov.dev/iptv/iptv-docs:latest` | Сайт документации                           |

Сервис `iptvc` публикует порт `8800`, а `docs` — порт `8801`.

KeyDB публикует порт, заданный `KEYDB_PORT`, по умолчанию `6379`.

Сервис `iptvc` зависит от `keydb` и запускается с командой `serve --check --repeat 0`.

Это поднимает веб-сервер и запускает бесконечную фоновую проверку.

## Запуск { id="start" }

После подготовки файлов соберите и запустите окружение из корня проекта:

```bash
docker compose up -d --build
```

Проверьте состояние контейнеров и журналы:

```bash
docker compose ps
docker compose logs -f iptvc
```

Веб-интерфейс приложения доступен на `http://localhost:8800`.

Документация доступна на `http://localhost:8801`.

Для остановки окружения выполните:

```bash
docker compose down
```

## Реверс-прокси и SSL { id="reverse-proxy" }

Для публикации приложения на домене с HTTPS настроим реверс-прокси, который будет терминировать SSL и проксировать запросы на контейнеры `iptvc` (порт `8800`) и `docs` (порт `8801`).

Ниже рассмотрены два варианта: nginx и Apache2.

!!! tip "site.base-url"
    После настройки домена укажите внешний адрес в `config.yml` или `.env`:

    ```yaml
    site:
      base-url: https://example.com
    ```

    Или через переменную окружения:

    ```bash
    SITE_BASE_URL=https://example.com
    ```

### Подготовка { id="reverse-proxy-prep" }

Убедитесь, что:

- домен `example.com` (и при необходимости `docs.example.com`) направляет A-запись на IP сервера;
- порты `80` и `443` открыты в файрволе;
- Docker-окружение запущено (`docker compose up -d`);
- порты `8800` и `8801` доступны локально (проверьте `curl -I http://localhost:8800`).

### nginx { id="reverse-proxy-nginx" }

Установите nginx и Certbot:

```bash
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx
```

Создайте конфигурацию для приложения:

```nginx title="/etc/nginx/sites-available/iptvc" linenums="1"
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8800;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

При необходимости добавьте отдельный `server`-блок для документации:

```nginx title="/etc/nginx/sites-available/iptv-docs" linenums="1"
server {
    listen 80;
    server_name docs.example.com;

    location / {
        proxy_pass http://127.0.0.1:8801;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Включите конфигурации и проверьте синтаксис:

```bash
sudo ln -s /etc/nginx/sites-available/iptvc     /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/iptv-docs /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

Получите SSL-сертификат через Certbot:

```bash
sudo certbot --nginx -d example.com -d docs.example.com
```

Certbot автоматически изменит конфигурацию nginx, добавит HTTPS и настройке редирект с HTTP на HTTPS.

Проверьте автоматическое продление:

```bash
sudo certbot renew --dry-run
```

### Apache2 { id="reverse-proxy-apache" }

Установите Apache2 и Certbot:

```bash
sudo apt update
sudo apt install -y apache2 certbot python3-certbot-apache
```

Включите необходимые модули:

```bash
sudo a2enmod proxy proxy_http ssl rewrite headers
sudo systemctl restart apache2
```

Создайте конфигурацию виртуального хоста для приложения:

```apache title="/etc/apache2/sites-available/iptvc.conf" linenums="1"
<VirtualHost *:80>
    ServerName example.com

    ProxyPreserveHost On
    ProxyPass        / http://127.0.0.1:8800/
    ProxyPassReverse / http://127.0.0.1:8800/

    RequestHeader set X-Forwarded-Proto "http"
    RequestHeader set X-Forwarded-Port  "80"
</VirtualHost>
```

При необходимости добавьте виртуальный хост для документации:

```apache title="/etc/apache2/sites-available/iptv-docs.conf" linenums="1"
<VirtualHost *:80>
    ServerName docs.example.com

    ProxyPreserveHost On
    ProxyPass        / http://127.0.0.1:8801/
    ProxyPassReverse / http://127.0.0.1:8801/

    RequestHeader set X-Forwarded-Proto "http"
    RequestHeader set X-Forwarded-Port  "80"
</VirtualHost>
```

Включите конфигурации и проверьте синтаксис:

```bash
sudo a2ensite iptvc iptv-docs
sudo apache2ctl configtest
sudo systemctl reload apache2
```

Получите SSL-сертификат через Certbot:

```bash
sudo certbot --apache -d example.com -d docs.example.com
```

Certbot автоматически создаст HTTPS-виртуальные хосты и настроит редирект с HTTP на HTTPS.

Проверьте автоматическое продление:

```bash
sudo certbot renew --dry-run
```

### Проверка { id="reverse-proxy-check" }

После настройки откройте в браузере:

- `https://example.com` — веб-интерфейс `iptvc`;
- `https://docs.example.com` — сайт документации.

Убедитесь, что сертификат валиден, а редирект с HTTP на HTTPS работает.

!!! note "Ограничение портов"
    После настройки реверс-прокси можно убрать публикацию портов `8800` и `8801` наружу в `compose.yml`, оставив их доступными только локально.
    Это предотвратит прямой доступ к сервисам в обход прокси.

## Сборка образа iptvc { id="image" }

Для сборки и публикации образа используйте цели Makefile в каталоге `iptvc/`:

```bash
cd iptvc

# Сборка одноархитектурного образа (linux/amd64 по умолчанию)
make image

# Сборка под arm64
make image GOARCH=arm64

# Сборка с указанием тега
make image IMAGE_TAG=v1.2.3
```

Для публикации multi-arch манифеста (linux/amd64 + linux/arm64):

```bash
make image-all
```

Цель `image-all` всегда отправляет образ в registry — это ограничение `docker buildx`: multi-arch манифест нельзя загрузить в локальный Docker daemon.

Перед публикацией войдите в registry, если это требуется вашей настройкой:

```bash
docker login git.axenov.dev
```

!!! warning "Рабочее дерево Git"
    Версия и коммит вшиваются в бинарь из `git describe` и `git rev-parse` на хосте в момент запуска `make`.
    Перед сборкой убедитесь, что рабочая копия чистая и находится на нужном теге или коммите.

## Обновление { id="update" }

После изменения конфигурации или исходного кода пересоберите и перезапустите сервисы:

```bash
docker compose up -d --build
```

Чтобы пересобрать только приложение `iptvc`:

```bash
docker compose build iptvc
docker compose up -d iptvc
```

Чтобы использовать опубликованный образ вместо локальной сборки, загрузите его и пересоздайте сервис:

```bash
docker compose pull iptvc
docker compose up -d iptvc
```

Обновление документации выполняется пересборкой сервиса `docs`:

```bash
docker compose build docs
docker compose up -d docs
```

## Диагностика { id="diagnostics" }

Для просмотра журналов отдельных сервисов используйте:

```bash
docker compose logs -f iptvc
docker compose logs -f keydb
docker compose logs -f docs
```

Для проверки конфигурации Compose выполните:

```bash
docker compose config
```

Если `iptvc` не подключается к кешу, проверьте, что в `.env` параметр `CACHE_HOST` имеет значение `keydb`, а сервис `keydb` запущен.