# 🚀 Installation (Docker & Binaries) Tuliprox is designed to run flawlessly in modern DevOps infrastructures (Docker/Kubernetes) but can also be executed as a standalone binary on Linux, Windows, or macOS for lightweight setups. This guide covers the installation using precompiled artifacts. If you want to compile Tuliprox from source, create custom Docker images, or build the documentation yourself, please refer to the [Build & Deploy (For Professionals)](build-and-deploy.md) chapter. --- ## 1. Running via Docker (Recommended) The recommended way for production use is Docker. Tuliprox does not require external database containers (everything uses internal embedded `.db` B+Tree files), making the setup extremely lightweight. You can pull the ready-to-use images directly from the GitHub Container Registry (`ghcr.io`). ### The Ideal `docker-compose.yml` ```yaml services: tuliprox: container_name: tuliprox image: ghcr.io/euzu/tuliprox-alpine:latest user: "133:144" # (Recommended) Run as non-root User (UID:GID of your host system) working_dir: /app volumes: - /opt/tuliprox/config:/app/config - /opt/tuliprox/data:/app/data - /opt/tuliprox/backup:/app/backup - /opt/tuliprox/downloads:/app/downloads - /opt/tuliprox/cache:/app/cache environment: - TZ=Europe/Berlin ports: - "8901:8901" restart: unless-stopped healthcheck: test: ["CMD", "/app/tuliprox", "-p", "/app/config", "--healthcheck"] interval: 30s timeout: 10s retries: 3 start_period: 10s ``` ### Volume Mapping (Technical Background) The separation of volumes is critical for security and performance: | Mount Point | Explanation & Technical Background | | :--- | :--- | | `/app/config` | Must contain your YAML files (`config.yml`, `source.yml`, etc.). Monitored by Tuliprox for file system events (`config_hot_reload`). | | `/app/data` | The `storage_dir`. Contains **Runtime Data**. Tuliprox recursively creates B+Tree databases (`*.db`), M3U caches, and TMDB metadata here. **THIS MUST BE PERSISTENT!** If lost during a restart, Tuliprox will attempt to redownload and FFprobe tens of thousands of streams, inevitably leading to provider bans. | | `/app/backup` | Destination folder for configuration backups triggered via the Web UI. | | `/app/downloads` | Destination folder for local video downloads initiated via the Web UI. | | `/app/cache` | Destination folder for local image downloads initiated via the xtream codes or m3u api use. | ### Managing Secrets with `.env` Files To keep provider credentials and tokens out of version control, use a `.env` file referenced by `${env:VAR}` in your configuration files. In Docker, three methods are supported: - **Automatic Discovery via Config Mount (Recommended):** Place your `.env` file directly inside your host config directory (e.g. `/opt/tuliprox/config/.env`). Because `/app/config` is mounted, Tuliprox automatically discovers and loads `/app/config/.env` at process launch before any configuration file is processed. - **Custom Location via `TULIPROX_ENV_FILE`:** Mount the `.env` file to an arbitrary path inside the container and specify `TULIPROX_ENV_FILE`: ```yaml environment: - TZ=Europe/Berlin - TULIPROX_ENV_FILE=/secrets/.env volumes: - /path/to/my-secrets.env:/secrets/.env:ro - /opt/tuliprox/config:/app/config ``` - **Native Docker Compose `env_file:` Directive:** Let Docker Compose populate container environment variables directly from a host `.env` file without mounting: ```yaml env_file: - .env ``` > **Important:** Changes to mounted `.env` files require restarting the container (`docker compose restart`). If using > Compose `env_file:`, recreate the container (`docker compose up -d --force-recreate`) to apply changed values. > Environment variables are loaded strictly once at application launch for thread safety. ### Docker Image Variants (`scratch` vs. `alpine`) Two distinct flavors are available in the container registry: 1. **`scratch-final` (`ghcr.io/euzu/tuliprox:latest`)**: This is an extremely hardened, minimalist image (`FROM scratch`). It contains *only* the statically linked Tuliprox binary, FFmpeg/FFprobe binaries, and CA certificates (for HTTPS/TMDB requests). There is no shell (`/bin/sh`), no package manager, and no system libraries. **Advantage:** Maximum security and minimal attack surface (DevSecOps Best Practice). **Disadvantage:** You cannot `docker exec` into the container for manual debugging. 2. **`alpine-final` (`ghcr.io/euzu/tuliprox-alpine:latest`)**: Based on Alpine Linux. Contains a shell, Tini (init system), and basic tools. **Advantage:** Ideal for debugging. You can `docker exec -it tuliprox sh` to inspect logs or run manual `curl`/`ffprobe` tests from within the container's network namespace to verify provider blocks. --- ## 2. Precompiled Standalone Binaries If you prefer running Tuliprox bare-metal without Docker, you can download the precompiled binaries for your operating system (Linux, Windows, macOS, ARM). 1. Go to the [Releases page on GitHub](https://github.com/euzu/tuliprox/releases). 2. Download the archive matching your OS and Architecture. 3. Extract the binary and place it in your desired home directory. 4. Run it via the CLI commands detailed below. --- ## 3. CLI Usage & Runtime Modes Tuliprox can operate in two primary modes. Running the compiled binary directly is the best way to test configurations locally before deploying them to production. ### Server Mode (Persistent Operation) Run Tuliprox as a persistent IPTV proxy server: ```bash ./tuliprox -s -c config/config.yml -i config/source.yml ``` This mode enables: - The Web UI Dashboard - The active Reverse-Proxy Streaming Engine - API endpoints (Xtream/M3U for players) - Background Workers (Metadata Scanner, DNS Resolver, Scheduler) ### CLI Mode (One-Shot Processing) Without the `-s` flag, Tuliprox runs as a one-time processor: ```bash ./tuliprox -c config/config.yml -i config/source.yml ``` It loads the configuration, downloads provider lists, applies all filters and mappings, writes the final database/M3U files to the `storage_dir`, and gracefully exits. *Useful for: Generating static playlists, debugging mappings, or running via external cronjobs.* ### CLI Arguments Reference You can view all arguments using `./tuliprox --help`: | Flag | Purpose | | :--- | :--- | | `-H, --home ` | Sets the home directory (base for config, storage, backup, downloads). Overrides all defaults. | | `-p, --config-path ` | Path to the config directory. | | `-c, --config ` | Specific path to the `config.yml`. | | `-i, --source ` | Specific path to the `source.yml`. | | `-m, --mapping ` | Specific path to the mapping file/directory. | | `-T, --template ` | Specific path to the template file/directory. | | `-t, --target ` | **Target Override:** Forces processing of the specified target *only*. Extremely useful to quickly re-render a broken list via shell without blocking the entire system, even if `enabled: false` in config. | | `-a, --api-proxy ` | Specific path to the `api-proxy.yml`. | | `-s, --server` | Run in continuous Server Mode. | | `-l, --log-level ` | Override log level (e.g., `info`, `debug`, `trace`). | | `--genpwd` | Interactively generate a secure `Argon2id` password hash for the `user.txt`. | | `--healthcheck` | Checks the API over localhost. Returns Exit Code `0` if `{status: "ok"}`. Used by Docker. | | `--scan-library` | Triggers an incremental scan of local media directories. | | `--force-library-rescan` | Ignores modification timestamps and forces a full TMDB/PTT re-evaluation of local media. | | `--dbx`, `--dbm`, `--dbe`, `--dbv`, `--dbms` | Opens internal database viewers (see *Operations & Debugging*). | --- ## 4. Advanced Ecosystem Integration Tuliprox is built to be a team player. In the `docker/container-templates/` directory of the repository, you will find complete, production-ready stack templates: - **Traefik Integration:** Automated Let's Encrypt TLS, strict Content-Security-Policy headers, and ACME DNS-01 challenges. - **Gluetun (VPN) Integration:** Route your upstream provider requests through WireGuard tunnels to hide your server IP, utilizing SOCKS5 proxy sidecars. - **CrowdSec Integration:** Protect your Tuliprox instance against L7 AppSec attacks, path traversal, and brute-force attempts using Traefik Bouncers. *(For an in-depth implementation guide on these templates, see the [Build & Deploy (For Professionals)](build-and-deploy.md) and [Examples & Recipes](examples-recipes.md) chapters).