ttvdrops

Get notified when a new drop is available on Twitch

TL;DR (Arch Linux + PostgreSQL)

Install and initialize Postgres, then start the service:

sudo pacman -S postgresql
sudo -u postgres initdb -D /var/lib/postgres/data
sudo systemctl enable --now postgresql

Create a local role and database:

sudo -u postgres createuser -P ttvdrops
sudo -u postgres createdb -O ttvdrops ttvdrops

Point Django at the unix socket used by Arch (/run/postgresql):

POSTGRES_USER=ttvdrops
POSTGRES_PASSWORD=your_password
POSTGRES_DB=ttvdrops
POSTGRES_HOST=/run/postgresql
POSTGRES_PORT=5432

Linux (Systemd)

sudo useradd --create-home --home-dir /home/ttvdrops --shell /bin/fish ttvdrops
sudo passwd ttvdrops
sudo usermod -aG wheel ttvdrops
su - ttvdrops
git clone https://git.lovinator.space/TheLovinator/ttvdrops.git
cd ttvdrops
uv sync --no-dev

# Modify .env with the correct database credentials and other settings, then run migrations:
uv run python manage.py migrate

Install the systemd service from the repo:

sudo install -m 0644 tools/systemd/ttvdrops.socket /etc/systemd/system/ttvdrops.socket
sudo install -m 0644 tools/systemd/ttvdrops.service /etc/systemd/system/ttvdrops.service

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now ttvdrops.socket
sudo systemctl enable --now ttvdrops.service

curl --unix-socket /run/ttvdrops/ttvdrops.sock https://ttvdrops.lovinator.space

Enable Celery worker and Beat services:

sudo install -m 0644 tools/systemd/ttvdrops-celery-worker.service /etc/systemd/system/
sudo install -m 0644 tools/systemd/ttvdrops-celery-beat.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ttvdrops-celery-worker.service
sudo systemctl enable --now ttvdrops-celery-beat.service

Set TTVDROPS_PENDING_DIR in .env to the directory where Twitch JSON drop files are dropped:

TTVDROPS_PENDING_DIR=/mnt/fourteen/Data/Responses/pending

Development

uv run python manage.py createsuperuser
uv run python manage.py makemigrations
uv run python manage.py migrate
uv run python manage.py collectstatic
uv run python manage.py runserver
uv run pytest

Celery

Celery powers all periodic and background work. Three services are required:

Service file	Queues	Purpose
ttvdrops-celery-worker.service	imports, api-fetches, default	Twitch/Kick/Chzzk imports, backup
ttvdrops-celery-beat.service	—	Periodic task scheduler (Beat)

Start workers manually during development:

# All-in-one worker (development)
uv run celery -A config worker --queues imports,api-fetches,image-downloads,default --loglevel=info

# Beat scheduler (requires database Beat tables — run migrate first)
uv run celery -A config beat --scheduler django_celery_beat.schedulers:DatabaseScheduler --loglevel=info

# Monitor tasks in the browser (optional)
uv run celery -A config flower

Periodic tasks configured via CELERY_BEAT_SCHEDULE:

Task	Schedule	Queue
twitch.tasks.scan_pending_twitch_files	every 10 s	imports
kick.tasks.import_kick_drops	:01/:16/:31/:46	api-fetches
chzzk.tasks.discover_chzzk_campaigns	every 2 h	api-fetches
twitch.tasks.backup_database	daily 02:15 UTC	default
twitch.tasks.download_all_images	Sunday 04:00 UTC	image-downloads
twitch.tasks.import_chat_badges	Sunday 03:00 UTC	api-fetches

Image downloads also run immediately on record creation via post_save signals (Game, DropCampaign, DropBenefit, RewardCampaign).

Import Drops

uv run python manage.py better_import_drops <file|dir> [--recursive] [--verbose] [--crash-on-error] [--skip-broken-moves]

Import Chat Badges

Import Twitch's global chat badges for archival and reference:

uv run python manage.py import_chat_badges

Requires TWITCH_CLIENT_ID and TWITCH_CLIENT_SECRET environment variables to be set.

Create DB Backup

Create a zstd-compressed SQL dump (only twitch_ tables) in the datasets directory:

uv run python manage.py backup_db

Optional arguments:

uv run python manage.py backup_db --output-dir "<path>" --prefix "ttvdrops"

How the duck does permissions work on Linux?

sudo chown -R ttvdrops:http /home/ttvdrops/.local/share/TTVDrops/media/
sudo find /home/ttvdrops/.local/share/TTVDrops/media -type d -exec chmod 2775 {} \;
sudo find /home/ttvdrops/.local/share/TTVDrops/media -type f -exec chmod 664 {} \;

sudo chown -R ttvdrops:http /home/ttvdrops/.local/share/TTVDrops/datasets/
sudo find /home/ttvdrops/.local/share/TTVDrops/datasets -type d -exec chmod 2775 {} \;
sudo find /home/ttvdrops/.local/share/TTVDrops/datasets -type f -exec chmod 664 {} \;