Installation

Published from docs/installation.md. To change this page, edit the source guide and open a pull request.

Installation

Run TDM on your own computer or home server with Docker. The v2.4.0 image includes the dashboard's Twitch login browser, optional desktop-helper access, and automatic session renewal. No desktop or display is needed on the server. Older images use their release's authentication instructions.

Docker

Pull and start the published image:

docker pull rangermix/twitch-drops-miner:2.4.0
docker run -d \
  --name twitch-drops-miner --init --stop-timeout 30 --shm-size 256m \
  -p 8080:8080 -e TZ=Australia/Sydney \
  -v "${PWD}/data:/app/data" \
  --restart unless-stopped \
  rangermix/twitch-drops-miner:2.4.0

Open http://localhost:8080. From another computer on your home network, use the miner host's LAN address, such as http://192.168.1.10:8080.

Version 2.4.0 checks dashboard host names. Custom names such as nas.lan need ALLOWED_HOSTS, or PUBLIC_BASE_URL for a reverse proxy. See allowed host names before updating an installation that uses a custom address.

The data mount keeps settings and login credentials outside the container. The init process and shutdown timeout let TDM close its temporary renewal browser when stopped. Only the dashboard port is needed; do not publish a browser or browser-control port.

The data and log mounts must enforce private Linux directory permissions. If your host bind mount ignores them, use a Docker named volume, for example -v twitch-drops-miner-data:/app/data in place of the data bind mount above. Preserve that volume when updating. Copy existing data from a private backup while TDM is stopped before changing mounts; a new empty volume does not contain the old login or settings.

To build a source checkout, run docker build --pull -t twitch-drops-miner . from the repository root and use twitch-drops-miner as the image in the run command above. Source builds use the current upstream Python/Alpine images through floating python:alpine and alpine:latest tags. For a security rebuild, run docker build --pull --no-cache -t twitch-drops-miner . to refresh base images and Alpine packages. The runtime includes noVNC's browser library; its unused websockify server dependencies are excluded. Published images need a maintainer rebuild to pick up fixes; Chromium updates depend on availability in Alpine's repositories.

To retain file logs outside the container, also mount ./logs:/app/logs. You can read the container's console output with:

docker logs --tail 100 twitch-drops-miner

Docker Compose

Check that Compose is installed with docker compose version. Choose the published image for a release installation, or build a source checkout if you want to run its code. Commands below use Bash; run Compose commands from the folder containing your chosen Compose file.

Published image

For a new installation, create a dedicated folder and save the following as compose.yaml. No Git clone or local image build is needed. Set TZ to match the timezone of your home internet connection before starting:

services:
  twitch-drops-miner:
    image: rangermix/twitch-drops-miner:2.4.0
    container_name: twitch-drops-miner
    init: true
    stop_grace_period: 30s
    shm_size: 256m
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    environment:
      TZ: Australia/Sydney
    restart: unless-stopped

Start it from that folder:

docker compose pull && docker compose up -d

This example pins 2.4.0, like the Docker quick start. Change the image tag to choose another release, or use latest to select the current stable image whenever you pull and recreate. The restart policy does not update images automatically.

Compose stores data in ./data and file logs in ./logs, relative to compose.yaml. Keep this folder and its mounts when updating. The directory-permission requirements apply to both mounts; use Docker named volumes if your host cannot enforce them. The init process, 30-second shutdown grace period, shared memory, and timezone support the integrated browser. Only port 8080 is published.

Open http://localhost:8080, or http://YOUR-SERVER:8080 from another device on your home network, and follow Twitch login. To protect access or use your own reverse proxy, follow Dashboard access.

Build a source checkout

The repository's docker-compose.yml builds source locally. For a new checkout:

git clone https://github.com/rangermix/TwitchDropsMiner.git && cd TwitchDropsMiner

Edit TZ in docker-compose.yml to match your home internet connection, then build and start from the repository root:

docker compose up -d --build

For a security rebuild, run docker compose build --pull --no-cache, then docker compose up -d to recreate the service with refreshed base images and packages.

The included file keeps data in ./data and logs in ./logs and includes the same browser settings as the published-image example. The default branch may contain unreleased changes. To build a particular revision, check it out before starting. Keep the published-image compose.yaml in a separate folder: Compose prefers that filename over docker-compose.yml when both are present.

Manage the service

Run these from the same Compose project folder:

Action	Command
Check status	docker compose ps
Follow recent console logs	docker compose logs --tail 100 -f twitch-drops-miner
Stop mining	docker compose stop
Start the stopped container	docker compose start

See Compose update steps to apply a new image or source revision. Keep the same data/log mounts and project configuration. Do not use docker compose down -v for updates; it can delete Compose-managed data volumes.

Switch an existing docker run installation to Compose

Use the published-image configuration above, but set its data mount to the exact directory or named volume used by your old container. Inspect the existing mount with the Docker update instructions before changing anything. An absolute bind path avoids accidentally selecting a new ./data folder. For an existing named volume, declare it under top-level volumes: with external: true and name: set to its exact Docker volume name, then reference that volume key in the service's /app/data mount.

Preserve your container name, ports, timezone, network configuration, and any custom mounts or environment variables such as PUBLIC_BASE_URL. Back up data privately while the miner is stopped and copy any unmounted logs you need before removing the old container. From the folder containing the prepared compose.yaml, run:

docker compose pull &&
docker stop --timeout 30 twitch-drops-miner &&
docker rm twitch-drops-miner &&
docker compose up -d

Adapt the container name if you changed it. Compose creates its own managed container after the old one is removed; reusing the same mount retains the saved data. Do not run the old and new miners against the same data directory at the same time.

For more Compose options, see the Docker Compose documentation.

Run from source

Install Python 3.12 or newer and uv. The miner host also needs a Chromium executable named chromium or chromium-browser on its PATH for automatic renewal. On Linux, also install xvfb and xauth (for example sudo apt install xvfb xauth on Debian or Ubuntu) so xvfb-run is available. Without it the renewal browser runs headless and the miner logs a warning each time it starts; Twitch can reject the session it issues, reported as reason=headless_fallback. The Docker image already includes these tools.

Docker includes the tools needed for new interactive login. The integrated desktop requires a separate unprivileged browser user and private miner data/log permissions; the image configures these automatically. The desktop helper can handle interactive sign-in on another home computer; the miner still needs Chromium for verification and renewal. Embedded-browser source requirements are listed in the login guide. From the repository root:

uv venv env --python 3.12
source env/bin/activate
uv sync --active --locked --python 3.12
python main.py

Create env/ only on the first setup. Activate it before later Python commands; --active keeps dependency installation in that environment. Open http://localhost:8080 after starting the miner. The source process must stay running for mining and automatic renewal to continue.

If you plan to modify the application, use the development setup in CONTRIBUTING.md, which includes the additional development tools.

Persistent data and upgrades

Keep the same data directory when updating or recreating the miner. Docker uses /app/data inside the container; the examples above mount it from ./data. A source installation uses data/ in the repository.

The directory contains settings, Twitch credentials, local drop history, and optional dashboard password state. Keep it private and back it up privately while the miner is stopped. Run only one miner process per data directory.

Review the release notes before updating.

Published image (docker run)

Use these Bash commands for a container created with docker run. Run them from the same folder used at installation: ${PWD}/data must resolve to the existing data directory. If you are unsure, inspect the mounts before removing the old container:

docker inspect --format '{{json .Mounts}}' twitch-drops-miner

Find the mount whose Destination is /app/data. For a bind mount, reuse its Source path; for a named volume, reuse its Name as -v VOLUME_NAME:/app/data. Do not substitute a new empty directory or volume. Keep your existing container name, timezone, ports, additional mounts (such as logs), network options, and environment variables (such as PUBLIC_BASE_URL) when adapting the example below. Files stored only inside the old container, including unmounted logs, are removed with it; copy any you need before removal.

docker pull rangermix/twitch-drops-miner:latest &&
docker stop --timeout 30 twitch-drops-miner &&
docker rm twitch-drops-miner &&
docker run -d \
  --name twitch-drops-miner --init --stop-timeout 30 --shm-size 256m \
  -p 8080:8080 -e TZ=Australia/Sydney \
  -v "${PWD}/data:/app/data" \
  --restart unless-stopped \
  rangermix/twitch-drops-miner:latest

latest selects the current stable published image at pull time. To select a specific release, replace latest in both commands with its version tag. Pulling downloads the image; recreating the container applies it. Restarting alone does not update the image, and --restart unless-stopped is not an automatic updater. The && separators stop the sequence if a command fails, so a failed pull leaves the existing container running. Reusing the data mount preserves stored settings, Twitch credentials, drop history, and dashboard password state.

Updating with Docker Compose

For the published-image Compose setup, change the image: tag in compose.yaml to the desired release first, or keep latest if that is what you selected. From that Compose project's directory, run:

docker compose pull && docker compose up -d

Compose pulls the selected image and recreates the service when its image or configuration changes, preserving its mounts. There is no need to remove the service manually. A version tag such as 2.4.0 stays on that release until you change it.

For the repository's Compose file, run this from your original Git clone on the branch you intend to update:

git pull --ff-only && docker compose up -d --build

This builds the updated checkout and recreates the service when needed, retaining its configured mounts. A branch such as main may include unreleased changes. If you downloaded a source archive or checked out a release tag, update to your chosen source revision first and retain the same data/log paths before rebuilding.

Keep the same project, mounts, and environment configuration. Do not use docker compose down -v during an update; it can delete Compose-managed data volumes.

Source installation

Stop the miner, update the checkout, activate env/, run uv sync --active --locked --python 3.12, and start it again.

Preserve data/cookies.jar. Working Android sessions are reused automatically. Smart TV sessions from v1.3.1/v1.3.2, expired sessions, and signed-out installations use the dashboard browser. Do not delete all data to solve a login problem.

All guides · Next: Twitch login