docs/content/iptvc/site/deploy.md

icon, tags

icon	tags
material/upload-network	iptvc docker deploy nginx apache ssl

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

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

:material-flag-checkered: Базовый вариант развёртывания сервиса

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

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

./iptvc serve

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

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

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

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

Список плейлистов — playlists.ini

!!! info "Синтаксис описан в этом разделе документации"

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

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

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

Но все они будут серого цвета и будет доступна только базовая информация о них. Зато будут работать короткие ссылки и их уже можно будет казывать в своём любимом плеере.

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

./iptvc serve --check

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

Список правил — channels.json

!!! info "Синтаксис описан в этом разделе документации"

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

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

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

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

1. продолжать пользоваться сервисом как есть;
2. подготовить свой файл channels.json согласно его правил синтаксиса;
3. скачать готовый файл из репозитория: channels.json

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

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

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

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

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

!!! info "Синтаксис описан в этом разделе документации"

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

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

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

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

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

:simple-docker: Развёртывание через Docker

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

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

Для этого нужно будет скачать ещё один файл из репозитория: compose.yml

---

---

---

Подготовка репозитория

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

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

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

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

Настройка файлов

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

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 — внешний адрес приложения.

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

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.

Состав окружения

Файл 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.

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

Запуск

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

docker compose up -d --build

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

docker compose ps
docker compose logs -f iptvc

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

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

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

docker compose down

Реверс-прокси и SSL

Для публикации приложения на домене с 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
```

Подготовка

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

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

nginx

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

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

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

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-блок для документации:

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;
    }
}

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

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:

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

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

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

sudo certbot renew --dry-run

Apache2

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

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

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

sudo a2enmod proxy proxy_http ssl rewrite headers
sudo systemctl restart apache2

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

<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>

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

<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>

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

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

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

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

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

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

sudo certbot renew --dry-run

Проверка

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

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

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

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

Сборка образа iptvc

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

cd iptvc

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

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

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

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

make image-all

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

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

docker login git.axenov.dev

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

Обновление

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

docker compose up -d --build

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

docker compose build iptvc
docker compose up -d iptvc

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

docker compose pull iptvc
docker compose up -d iptvc

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

docker compose build docs
docker compose up -d docs

Диагностика

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

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

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

docker compose config

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