Skip to main content
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}
DirectoryPurpose
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.
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!"
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.
Use these credentials in any Xtream Codes-compatible player:
  • Server: http://192.168.1.41:8901
  • 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us