Quickstart

Get tuliprox running with Docker in under 5 minutes and serve your first IPTV playlist.

This guide gets you from zero to a working tuliprox setup using Docker. By the end you will have tuliprox running, connected to an IPTV provider, and serving a playlist you can open in Plex, Jellyfin, Emby or any IPTV player.

1. Create the directory layout

   Create directories for your tuliprox installation:

   mkdir -p /home/tuliprox/{config,data,cache}
   

   Directory	Purpose
   config/	Configuration files (config.yml, source.yml, api-proxy.yml)
   data/	Persisted playlists, databases and metadata
   cache/	Cached resources such as logos

2. Create docker-compose.yml

   Create /home/tuliprox/docker-compose.yml:

   docker-compose.yml

   services:
     tuliprox:
       container_name: tuliprox
       image: ghcr.io/euzu/tuliprox-alpine:latest
       working_dir: /app
       volumes:
         - /home/tuliprox/tuliprox:/app/tuliprox
         - /home/tuliprox/config:/app/config
         - /home/tuliprox/data:/app/data
         - /home/tuliprox/cache:/app/cache
       environment:
         - TZ=Europe/Paris
       ports:
         - "8901:8901"
       restart: unless-stopped
   

   Adjust TZ to your timezone and update the volume paths if you chose different directories.

3. Create config.yml

   Create /home/tuliprox/config/config.yml:

   config/config.yml

   api:
     host: 0.0.0.0
     port: 8901
     web_root: ./web
   storage_dir: ./data
   update_on_boot: true
   

   Set update_on_boot: false while testing to avoid immediately downloading from your provider. Enable it once everything looks correct.

4. Create source.yml

   Create /home/tuliprox/config/source.yml with your provider details.

   Xtream Codes provider

   config/source.yml

   templates:
     - name: ALL_CHAN
       value: 'Group ~ ".*"'
   inputs:
     - type: xtream
       name: my_provider
       url: http://YOUR-PROVIDER-URL:8080
       username: YOUR_USERNAME
       password: YOUR_PASSWORD
   sources:
     - inputs:
         - my_provider
       targets:
         - name: all_channels
           output:
             - type: xtream
           filter: "!ALL_CHAN!"
   

   M3U provider

   config/source.yml

   templates:
     - name: ALL_CHAN
       value: 'Group ~ ".*"'
   inputs:
     - type: m3u
       name: my_provider
       url: http://YOUR-PROVIDER-URL/get.php?username=USER&password=PASS&type=m3u_plus
   sources:
     - inputs:
         - my_provider
       targets:
         - name: all_channels
           output:
             - type: m3u
           filter: "!ALL_CHAN!"
   

   Replace the URL, username and password with your actual provider credentials.

5. Create api-proxy.yml

   Create /home/tuliprox/config/api-proxy.yml to define which users can connect to tuliprox:

   config/api-proxy.yml

   server:
     - name: default
       protocol: http
       host: 192.168.1.41
       port: 8901
       timezone: Europe/Berlin
       message: Welcome to tuliprox
   user:
     - target: all_channels
       credentials:
         - username: myuser
           password: mypassword
           proxy: redirect
           server: default
   

   Replace 192.168.1.41 with the LAN IP address of the machine running tuliprox. This is the address your media clients will use.

6. Start tuliprox

   docker compose up -d
   

   Open http://localhost:8901 in your browser. The Web UI should load. Go to Settings to verify your configuration was loaded correctly.

   Check the logs if tuliprox does not start: docker compose logs -f tuliprox

7. Connect your media client

   Once tuliprox is running and the playlist has been fetched from your provider, connect your media client using one of these URL formats.

   Xtream Codes

   Use these credentials in any Xtream Codes-compatible player:

   • Server: http://192.168.1.41:8901
   • Username: myuser
   • Password: mypassword

   M3U playlist

   Use this URL in any M3U player:

   http://192.168.1.41:8901/get.php?username=myuser&password=mypassword&type=m3u_plus
   

   XMLTV / EPG

   Use this URL for your EPG source:

   http://192.168.1.41:8901/xmltv.php?username=myuser&password=mypassword
   

Good first milestone

1. Add one working input

   Confirm tuliprox can download your provider’s playlist without errors.

2. Create one target

   Set up a single target and verify the playlist output looks correct.

3. Confirm a stream works

   Open one stream in VLC or your media player to confirm end-to-end streaming.

4. Add filtering and mapping

   Once the basics work, add filters to remove unwanted channels, then add mapping rules to rename entries.

5. Enable the reverse proxy

   Configure the reverse proxy mode to get user limits, stream sharing and fallback videos.

Keep failures local. Add one feature at a time and verify it works before moving on. This makes provider-specific issues much easier to diagnose.

What’s next

Getting started

Learn about run modes, all CLI arguments and the project layout.

Configuration reference

Explore all configuration options for config.yml, source.yml and api-proxy.yml.

Filtering and mapping

Write filter expressions and mapping rules to shape your playlist.

Streaming and proxy

Configure reverse proxy mode for user limits and stream sharing.