iptv-tool: an EPG server for IPTV apps, in a 20 MB container

Three jobs that usually live in three separate scripts

The project describes itself as an IPTV toolbox with Docker deployment, supporting EPG management, live source management and logo management, and compatible with the DIYP and Baichuan formats, with the Super Live format, and with xmltv.

Those three jobs are the reason this is a single application rather than a set of scripts. Guide data has to be stored somewhere and kept up to date, and it has to be matched against the channel names in a playlist, which are written by whoever put the playlist together and bear no relation to the guide's naming. Channel logos are keyed by channel name as well, so they have to be matched through the same map. If the matching lives in one place, the three data sets stay consistent with each other.

The container is small, which is a deliberate constraint. It is based on Alpine and the README says it is 20 MB compressed, and it is published for amd64, arm64 and armv7, so it runs on the small boxes and single board computers that people actually run these things on.

The application itself is PHP on nginx with php-fpm, and the image carries a long list of extensions, among them pdo_mysql, pdo_pgsql, pdo_sqlite, redis and memcached. The storage choice is yours, SQLite or MySQL, and the README notes that a phpLiteAdmin management tool is built in.

The audience is a person running their own television setup, and the guide data, the playlist and the logos all sit behind a web page that the README calls simple and easy to use.

Channel matching is where the real work happens

Every feature in this project depends on one operation, which is deciding that the channel called CCTV1综合 in one playlist is the same channel as the one called CCTV-1 in a guide file.

The matching layer supports traditional Chinese channel matching and fuzzy matching, and it supports channel aliases and regular expressions. The alias list is the manual part, and the regular expression part is the powerful part. The README documents the syntax: a rule contains regex:, and the example replaces a family of channel names with a normalised form while excluding specific variants.

That example is worth understanding, because it shows the shape of the problem. A regular expression matches CCTV 1综合, CCTV-4K频道, CCTV - 5+频道 and CCTV - 5PLUS频道 and rewrites them to CCTV1, CCTV4K, CCTV5+ and CCTV5PLUS, while the negative part excludes CCTV4美洲 and CCTV4欧洲, which are the international feeds of the same numbered channel. Without that exclusion, a fuzzy match on the number alone would put the American feed of CCTV-4 in the guide for the domestic one, and the mistake would be invisible in the output.

This is why the logo management and the guide management both talk about fuzzy matching, and it is also why the matching list is one of the first things to customise in the interface settings. The logic is right in the container, and the data is what makes it correct.

The output side has the same problem in reverse, and the answer is a set of formats rather than one. The tool can return DIYP and Baichuan format, Super Live format and xmltv, and it can generate a guide for specified channels matched against an M3U file. The client is not asked to understand your source data, because your source data cannot be understood by anyone else either.

Installing is a script you should read before you pipe to bash

The recommended deployment runs an install script, and the README offers three mirrors of it: the raw GitHub URL, a Gitee mirror and a jsDelivr mirror.

bash <(curl -Ls https://raw.githubusercontent.com/taksssss/iptv-tool/master/install.sh)

The manual route is a single docker run, and the README documents each flag, which is the better place to start if you want to know what the script would have done.

docker run -d --name php-epg \
  -p 5678:80 \
  -v $HOME/epg:/htdocs/data \
  -e PHP_MEMORY_LIMIT=512M \
  -e ENABLE_FFMPEG=false \
  --restart unless-stopped \
  taksss/php-epg:latest

The host directory is the default data directory and the 5678 port is the default, both of which the README says you can change. PHP_MEMORY_LIMIT defaults to 512M. Enabling ffmpeg is a separate switch, and the README gives an alternative image for environments that cannot pull from Docker Hub directly.

HTTPS is a set of further flags rather than a separate image: a 5679 to 443 port mapping, ENABLE_HTTPS, FORCE_HTTPS to redirect, and two volume mounts for the certificate and the private key. The image itself exposes 80 and 443.

Upgrades are handled by a watchtower container rather than by the tool:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower php-epg --cleanup --run-once

That command mounts the Docker socket into a container, which is worth noticing. It is the standard way to auto-update containers, and it is also a container with control over the host's Docker daemon, running as a scheduled job.

The management page, the endpoints, and the empty password

Once the container is up, the README's usage steps are a short list. You open the management page in a browser, and the default password is empty, so you should set your own as needed. You add an EPG address, saving the configuration, then pull the data, and the log and the channel management pages show what happened. You set up a scheduled task and check its timetable.

The scheduling advice in the README is specific and worth following. It suggests starting the fetch around one in the morning, because many sources have no data between midnight and half past midnight, and fetching every six to twelve hours is enough.

The four output endpoints are then the interface your player actually uses. The xmltv endpoint is the base index.php, the DIYP and Baichuan endpoint is index.php with a ch parameter, the Super Live endpoint is index.php with a channel parameter, and the tvbox integration is a pair of templates for the guide and for the logo, the logo one using a type parameter of icon.

The result is then pasted into the EPG field of a client such as DIYP or TiviMate, and the README notes that some players do not follow the redirect on the xmltv file and can use the t.xml.gz or t.xml paths instead. There are also two keyboard shortcuts, Ctrl and S to save settings and Ctrl and / to comment out a selected EPG address.

Two operational details are worth flagging. The management interface is a plain web page behind a port, with access control handled by a TOKEN setting, User-Agent filtering and IP black and white lists, and the default password being empty means that configuration is the first thing to do after the first start, not the last.

Caching, the scheduled fetch, and the file manager nobody asked for

Three supporting features sit alongside the guide, and they tell you what the author actually needed this tool to do.

Caching is handled with Memcached integrated and Redis supported. For a service that regenerates the same guide file for every client that requests it, and where the same client may ask for the same channel list repeatedly, a cache is the difference between a cheap endpoint and a slow one.

Scheduled tasks support timed data updates, which is what makes the tool a server rather than a script you run by hand. The live source management features add aggregation of TXT and M3U sources, speed testing and a live source proxy, and the logo management adds fuzzy matching with a tvbox interface, so a channel's logo is resolved through the same matching layer that resolves its programme guide.

Then there is the file management, with tinyfilemanager integrated, and the README describes a settings page that is meant to be simple enough to use without a manual. Both are pragmatic additions for the person running the box, and both enlarge the surface of a container that is otherwise a small PHP application.

The environment also matters for the schedule. The container is built on Alpine with tzdata installed, and the time zone of the box is what the scheduled fetch will use, so a box left on UTC will fetch at a different local hour than the one in the morning the README recommends.

The compose file is a demonstration, not a recommendation

The repository ships a docker-compose.yml, and it is worth reading as a sample of a three-container deployment rather than as a production file.

services:
  php-epg:
    image: taksss/php-epg:latest
    container_name: php-epg
    volumes:
      - $HOME/epg:/htdocs/data
    ports:
      - "5678:80"

Alongside the application, the compose file runs MySQL 8.0 with a root password set in the file, a database named phpepg, and a user with the same name, and it adds phpMyAdmin mapped to port 8080 on the host. Every one of those is a development convenience, and the root password in a compose file is the kind of thing that ends up in a public repository and then in somebody's deployment.

The application image itself supports SQLite, so the MySQL service is optional, and the single docker run in the README is the simpler deployment. The compose file earns its place for somebody who wants the database to be inspectable with familiar tooling, and it is a reasonable starting point for a three-container arrangement.

The licence is GPL-2.0, with a LICENSE file in the repository, and the project has no GitHub releases, with the change history in CHANGELOG.md instead. The last push to the repository was on 2026-08-17. The tree itself is small, with the PHP application in an epg directory, an install.sh, a docker-compose.yml, a docker-entrypoint.sh, a pic directory of screenshots, and DONATIONS.md.

Editorial conclusion

iptv-tool fits someone running their own IPTV setup who wants a single server that stores guide data, matches it against a channel list, keeps logos in step and serves the result to several client formats. It does not fit a team that wants a general media platform, and the live source features deserve a moment of thought because a playlist proxy is only as lawful as the URLs in it. Before you deploy, set the management password, the TOKEN and the access lists, and decide whether you want the source proxy enabled at all.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. Project website
4. README
5. taksssss/iptv-tool on GitHub