Deploy an auto-updating IPTV playlist service with Docker

Once a playlist exceeds a few dozen channels, manual maintenance becomes impractical: changing a channel name requires editing a file, and adding a new device requires re-importing. Running a lightweight playlist service with Docker lets the NAS generate it on a schedule and provide a fixed address externally, so all players at home pull from this one address.

This article covers the deployment approach and Compose syntax; use only the sources you have the right to use (multicast addresses issued by operators, self-hosted sources).

I. Overall approach

1. Put the source list (channel name + address) as input in a directory on the NAS;
2. Use a container to periodically execute "detection + m3u generation";
3. The generated m3u is served externally via a Web port, and players directly enter this URL;
4. The container also writes detection results and logs to disk for traceability.

II. Directory preparation

First create the directory structure on the NAS, and mount both input and output into the container:

docker/
└── iptv/
    ├── data/          # 输出：生成的 m3u、日志
    │   └── playlist.m3u
    ├── source.txt     # 输入：你自己的频道清单
    └── docker-compose.yml

Input file formatDefine it simply yourself: one channel per line:

CCTV-1 综合|udp://@239.x.x.x:1234
湖南卫视|rtp://239.x.x.x:5678

III. docker-compose.yml

services:
  iptv:
    image: <你选用的镜像>
    container_name: iptv
    restart: unless-stopped
    ports:
      - "50086:50086"
    volumes:
      - ./data:/app/data
      - ./source.txt:/app/source.txt:ro
    environment:
      - TZ=Asia/Shanghai
      - CHECK_TIMEOUT=5          # 单个地址检测超时（秒）
      - CHECK_CONCURRENCY=8      # 并发数，别设太大
      - CRON=0 4 * * *           # 每天凌晨 4 点跑一次

Start:

docker compose up -d
docker compose logs -f      # 观察首次生成的输出

IV. Verification and usage

1. Access in a browser http://你的NAS_IP:50086/playlist.m3uIf you can see content, it means the service is working;
2. In the player, select "Add source → Import from URL" and enter the address above;
3. After modifying the source list, restart the container once, or wait for the scheduled task to automatically generate it at the scheduled time;
4. The generated m3u can be read directly by the IPTV plugins of Jellyfin / Emby / Plex; configure an XMLTV address separately for the program guide.

V. Several practical points

• Don't set concurrency too highOpening connections to hundreds of addresses at once can easily saturate a home router, which in turn causes many false positives.
• Results should be versionedKeep a dated copy of the generated file each day; if there is a problem, you can compare which day it started changing.
• Keep enough logsContainer logs are only useful during troubleshooting; it is recommended to output them to files and limit the size of a single file to avoid filling up the NAS.
• Do not expose ports to the public internetThis service is only for home use; do not map the port to the public internet. If external access is really needed, come back via VPN; do not expose it directly.
• Use a fixed LAN IPAssign the NAS a static address or DHCP reservation; otherwise, when the IP changes, all players need to be reconfigured.

6. Common Issues

Summary

Using containers to string together “detection + generation + distribution” turns playlist maintenance from “manually editing files” into “changing one line in the source list and leaving the rest to the scheduled task.” The value of this workflow lies in youfor the sources you have the right to usemanaging them uniformly—there are not many sources, but they are controllable, maintainable, and rollback-capable; this is the key to running long term.