---
title: Первые шаги
icon: material/rocket-launch
tags: ["iptvc", "serve", "сайт"]
---

# :material-rocket-launch: Первые шаги для запуска сайта

В этой статье мы шаг за шагом запустим собственный сайт-агрегатор IPTV-плейлистов — от простейшего варианта до полной конфигурации с кешем и тонкой настройкой проверки.

Программа `iptvc` уже должна быть [установлена](../install.md).
Все команды ниже выполняются в терминале из директории, где лежит бинарник.

---

## Шаг 1. Запускаем пустой сайт

Минимальный запуск — одна команда:

```bash
./iptvc serve
```

Сайт откроется на `http://localhost:8080`.
Это пустая страница: нет ни одного плейлиста, потому что программе пока неоткуда их взять.

Чтобы изменить порт или хост, не трогая файл конфигурации:

```bash
./iptvc serve -p 3000 --host 0.0.0.0
```

Подробнее об этих флагах — в [документации команды `serve`](../commands/serve.md).

---

## Шаг 2. Добавляем плейлисты

Список плейлистов описывается в файле [`playlists.ini`](../../common/formats/playlists.md).
Создадим его рядом с `iptvc`:

```ini title="playlists.ini"
[ru]
name = Российские каналы
desc = Основные федеральные каналы
pls = 'https://example.com/ru.m3u'
src = 'https://example.com/ru-playlist'

[movies]
name = Фильмы
pls = 'https://example.com/movies.m3u'
```

Каждая секция `[code]` — это плейлист.
Код используется в коротких ссылках вида `http://localhost:8080/ru`.
Параметр `pls` обязателен, остальные — по желанию.

Теперь запустим:

```bash
./iptvc serve
```

Сайт покажет оба плейлиста, но их статус — `unknown` (неизвестно).
Это нормально: программа знает о них, но ещё не проверяла.
Чтобы статусы появились, нужно включить фоновую проверку.

!!! tip "Путь к ini-файлу"
    Если файл лежит не рядом с программой, укажите путь через флаг [`-i`](../commands/serve.md#ini) или в [`config.yml`](../../common/config/config.md) → `app.playlists`.

---

## Шаг 3. Включаем фоновую проверку

Без проверки сайт просто показывает список.
Чтобы плейлисты и каналы проверялись автоматически, добавим флаг `--check`:

```bash
./iptvc serve --check
```

Теперь программа в фоне загружает каждый плейлист, парсит каналы и проверяет их доступность.
Результаты сразу попадают в оперативную память и отображаются на сайте.

Можно настроить интервал между циклами проверки:

```bash
# пауза 120 секунд между циклами, бесконечно
./iptvc serve --check --playlists-all-cooldown 120000

# проверить один раз и остановить
./iptvc serve --check --repeat 1
```

Если не хочется каждый раз писать `--check`, можно включить проверку через [`config.yml`](../../common/config/config.md):

```yaml title="config.yml"
check:
  start-on-serve: true
```

Тогда обычный `./iptvc serve` автоматически запустит фоновую проверку.

---

## Шаг 4. Настраиваем внешний вид сайта

Сайт можно настроить под себя: заголовок, иконку, навигацию в шапке и ссылки в подвале.
Всё это — в секции [`site`](../../common/config/config.md) файла `config.yml`.

```yaml title="config.yml"
site:
  base-url: http://localhost:8080
  repo-url: https://git.axenov.dev/IPTV
  page-size: 20                       # пагинация по 20 плейлистов на страницу (0 — без пагинации)
  favicon: /favicon.ico               # путь к иконке
  header:
    title: Мой IPTV                   # заголовок в шапке и вкладке браузера
    navigation:
      - title: Документация
        url: /docs
        icon: document-text-outline
      - title: Telegram
        icon: paper-plane-outline
        children:
          - title: Канал
            url: https://t.me/my_channel
            icon: megaphone-outline
          - title: Чат
            url: https://t.me/my_chat
            icon: chatbubbles-outline
  footer-links:
    - title: Исходники
      url: https://git.axenov.dev/IPTV
      icon: code-slash-outline
    - title: Мой сайт
      url: https://example.com
      icon: person-outline
```

--8<-- "ionicons-name.md"

!!! note "base-url"
    Параметр `base-url` используется для формирования внутренних ссылок.
    Если публикуете сайт на домене, укажите его здесь, например `https://my-iptv.ru`.

---

## Шаг 5. Добавляем теги каналам

Теги помогают посетителям находить каналы по темам: спорт, фильмы, музыка и так далее.
Правила описываются в файле [`channels.json`](../../common/formats/channels.md).

```json title="channels.json"
[
  {
    "tvg-id": "^ru-",
    "tags": ["russian"]
  },
  {
    "title": "спорт",
    "tags": ["sport"]
  },
  {
    "title": "кино|фильм",
    "tags": ["film"]
  }
]
```

Путь к файлу указывается в [`config.yml`](../../common/config/config.md) → `app.tags` или через флаг [`-t`](../commands/serve.md#tags):

```bash
./iptvc serve --check -t /path/to/channels.json
```

Полный список доступных тегов — в [справочнике по channels.json](../../common/formats/channels.md#доступные-теги).

---

## Шаг 6. Подключаем кеш (KeyDB/Redis)

По умолчанию результаты проверки хранятся только в оперативной памяти.
Если программу перезапустить — все результаты пропадут, и плейлисты снова станут `unknown` до следующей проверки.

Кеш решает эту проблему: результаты сохраняются в KeyDB (или Redis) и переживают перезапуск.
Включается одной строкой в [`config.yml`](../../common/config/config.md):

```yaml title="config.yml"
cache:
  enabled: true
  host: localhost
  port: 6379
  ttl: 1800          # секунды (30 минут)
```

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

```bash
CACHE_ENABLED=true CACHE_TTL=3600 ./iptvc serve --check
```

Или через флаги:

```bash
./iptvc serve --check --cache-enabled --cache-host 192.168.1.10 --cache-ttl 3600
```

!!! tip "KeyDB или Redis"
    KeyDB — это форк Redis, полностью совместимый по протоколу.
    Подойдёт любой из них.
    Если кеш включён, но сервер недоступен — сайт продолжит работать, просто без кеширования.

---

## Шаг 7. Тонкая настройка проверки

Когда плейлистов много, полезно управлять параллелизмом, таймаутами и задержками.
Все параметры — в секции [`check`](../../common/config/config.md) файла `config.yml`.

### Параллелизм

```yaml title="config.yml"
check:
  playlists:
    max-routines: 10       # сколько плейлистов проверять одновременно
    per-routine: 5         # сколько плейлистов в одной процедуре
  channels:
    max-routines: 100      # сколько каналов проверять одновременно
    per-routine: 20        # сколько каналов в одной процедуре
```

Чем больше значения — тем быстрее проверка, но выше нагрузка на процессор и сеть.
Начните со значений по умолчанию и увеличивайте при необходимости.

### Таймауты

```yaml title="config.yml"
check:
  playlists:
    timeout: 10000         # мс на загрузку плейлиста
  channels:
    timeout: 10000         # мс на проверку одного канала
    byte-range: 512        # сколько байт скачать от сервера канала
```

Если плейлисты или каналы медленные, увеличьте `timeout`.
Если сервер блокирует большие запросы — уменьшите `byte-range`.

### Задержки (cooldown)

Чтобы не перегружать серверы-источники, между проверками можно делать паузы.
Параметры поддерживают как фиксированное значение, так и диапазон `[min, max]` — тогда пауза будет случайной при каждом проходе:

```yaml title="config.yml"
check:
  playlists:
    all-cooldown: 5000           # 5 секунд после всех плейлистов
    one-cooldown: [1000, 3000]   # 1–3 секунды после каждого плейлиста
  channels:
    cooldown: [100, 500]         # 100–500 мс после каждого канала
```

### User-Agent

Некоторые серверы блокируют запросы без правильного User-Agent.
Можно указать один или несколько — тогда при каждом запросе будет выбран случайный:

```yaml title="config.yml"
check:
  playlists:
    user-agent:
      - Mozilla/5.0 WINK/1.31.1 (AndroidTV/9) HlsWinkPlayer
      - Mozilla/5.0 (Linux; Android 11) AppleWebKit/537.36
  channels:
    user-agent: Mozilla/5.0 (Linux; Android 11) AppleWebKit/537.36
```

Все эти параметры можно также задавать через [переменные окружения](../../common/config/config.md) или [CLI-флаги](../commands/serve.md) — они имеют наивысший приоритет.

---

## Полный пример

Соберём всё вместе в одном `config.yml`:

```yaml title="config.yml"
app:
  timezone: GMT+3
  debug: false
  log_level: info
  playlists: ./playlists.ini
  tags: ./channels.json

server:
  host: 0.0.0.0
  port: 8080

site:
  base-url: https://my-iptv.ru
  repo-url: https://git.axenov.dev/IPTV
  page-size: 20
  favicon: /favicon.ico
  header:
    title: Мой IPTV
    navigation:
      - title: Статус
        url: https://status.my-iptv.ru
        icon: pulse-outline
      - title: Документация
        url: /docs
        icon: document-text-outline
      - title: Telegram
        icon: paper-plane-outline
        children:
          - title: Канал
            url: https://t.me/my_channel
            icon: megaphone-outline
          - title: Чат
            url: https://t.me/my_chat
            icon: chatbubbles-outline
  footer-links:
    - title: Исходники
      url: https://git.axenov.dev/IPTV
      icon: code-slash-outline
    - title: Контакты
      url: https://example.com
      icon: person-outline

check:
  start-on-serve: true
  playlists:
    user-agent:
      - Mozilla/5.0 WINK/1.31.1 (AndroidTV/9) HlsWinkPlayer
      - Mozilla/5.0 (Linux; Android 11) AppleWebKit/537.36
    timeout: 10000
    all-cooldown: 5000
    one-cooldown: [1000, 3000]
    max-routines: 10
    per-routine: 5
  channels:
    user-agent: Mozilla/5.0 (Linux; Android 11) AppleWebKit/537.36
    timeout: 10000
    byte-range: 512
    cooldown: [100, 500]
    max-routines: 100
    per-routine: 20

cache:
  enabled: true
  host: localhost
  port: 6379
  ttl: 3600
```

Запуск:

```bash
./iptvc serve
```

Поскольку `start-on-serve: true`, фоновая проверка запустится автоматически.
Кеш включён, так что результаты переживут перезапуск.
Сайт доступен на `http://0.0.0.0:8080`.

---

## Docker

Удобно запускать сайт в контейнере. Образ `iptvc` уже включает бинарник:

```yaml title="compose.yml"
services:
  iptvc:
    image: git.axenov.dev/iptv/iptvc:latest
    command: [serve]
    ports:
      - "8080:8080"
    volumes:
      - ./config.yml:/app/config.yml:ro
      - ./playlists.ini:/app/playlists.ini:ro
      - ./channels.json:/app/channels.json:ro
    environment:
      - CHECK_START_ON_SERVE=true
      - CACHE_ENABLED=true
      - CACHE_HOST=keydb
      - CACHE_PORT=6379

  keydb:
    image: eqalpha/keydb:latest
    restart: unless-stopped
```

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

Подробнее об установке образа — в [документации по установке](../install.md).

---

## Краткая шпаргалка

| Задача                        | Как                                                     |
| ----------------------------- | ------------------------------------------------------- |
| Запустить сайт                | `./iptvc serve`                                         |
| С проверкой плейлистов        | `./iptvc serve --check`                                 |
| На другом порту               | `./iptvc serve -p 3000`                                 |
| С ini-файлом из другого места | `./iptvc serve -i /path/to/playlists.ini`               |
| С кешем                       | `./iptvc serve --check --cache-enabled`                 |
| Один цикл проверки            | `./iptvc serve --check --repeat 1`                      |
| Пауза 2 минуты между циклами  | `./iptvc serve --check --playlists-all-cooldown 120000` |
| Подробные логи                | `./iptvc serve --check --verbose`                       |

Полный список параметров — в [справочнике по `config.yml`](../../common/config/config.md), [переменным окружения](../../common/config/config.md) и [команде `serve`](../commands/serve.md).