> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/euzu/tuliprox/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Steps>
  <Step title="Create the directory layout">
    Create directories for your tuliprox installation:

    ```bash theme={null}
    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                              |
  </Step>

  <Step title="Create docker-compose.yml">
    Create `/home/tuliprox/docker-compose.yml`:

    ```yaml docker-compose.yml theme={null}
    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.
  </Step>

  <Step title="Create config.yml">
    Create `/home/tuliprox/config/config.yml`:

    ```yaml config/config.yml theme={null}
    api:
      host: 0.0.0.0
      port: 8901
      web_root: ./web
    storage_dir: ./data
    update_on_boot: true
    ```

    <Note>
      Set `update_on_boot: false` while testing to avoid immediately downloading from your provider. Enable it once everything looks correct.
    </Note>
  </Step>

  <Step title="Create source.yml">
    Create `/home/tuliprox/config/source.yml` with your provider details.

    <Tabs>
      <Tab title="Xtream Codes provider">
        ```yaml config/source.yml theme={null}
        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!"
        ```
      </Tab>

      <Tab title="M3U provider">
        ```yaml config/source.yml theme={null}
        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!"
        ```
      </Tab>
    </Tabs>

    Replace the URL, username and password with your actual provider credentials.
  </Step>

  <Step title="Create api-proxy.yml">
    Create `/home/tuliprox/config/api-proxy.yml` to define which users can connect to tuliprox:

    ```yaml config/api-proxy.yml theme={null}
    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.
  </Step>

  <Step title="Start tuliprox">
    ```bash theme={null}
    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.

    <Tip>
      Check the logs if tuliprox does not start: `docker compose logs -f tuliprox`
    </Tip>
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Xtream Codes">
        Use these credentials in any Xtream Codes-compatible player:

        * **Server**: `http://192.168.1.41:8901`
        * **Username**: `myuser`
        * **Password**: `mypassword`
      </Tab>

      <Tab title="M3U playlist">
        Use this URL in any M3U player:

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

      <Tab title="XMLTV / EPG">
        Use this URL for your EPG source:

        ```
        http://192.168.1.41:8901/xmltv.php?username=myuser&password=mypassword
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Good first milestone

<Steps>
  <Step title="Add one working input">
    Confirm tuliprox can download your provider's playlist without errors.
  </Step>

  <Step title="Create one target">
    Set up a single target and verify the playlist output looks correct.
  </Step>

  <Step title="Confirm a stream works">
    Open one stream in VLC or your media player to confirm end-to-end streaming.
  </Step>

  <Step title="Add filtering and mapping">
    Once the basics work, add filters to remove unwanted channels, then add mapping rules to rename entries.
  </Step>

  <Step title="Enable the reverse proxy">
    Configure the reverse proxy mode to get user limits, stream sharing and fallback videos.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## What's next

<CardGroup cols={2}>
  <Card title="Getting started" icon="book-open" href="/getting-started">
    Learn about run modes, all CLI arguments and the project layout.
  </Card>

  <Card title="Configuration reference" icon="sliders" href="/configuration/main-config">
    Explore all configuration options for config.yml, source.yml and api-proxy.yml.
  </Card>

  <Card title="Filtering and mapping" icon="filter" href="/guides/filtering-and-mapping">
    Write filter expressions and mapping rules to shape your playlist.
  </Card>

  <Card title="Streaming and proxy" icon="arrow-right-arrow-left" href="/features/streaming-and-proxy">
    Configure reverse proxy mode for user limits and stream sharing.
  </Card>
</CardGroup>