1
Setup and Configuration
Dymas edited this page 2026-10-17 13:04:59 +02:00

Setup and Configuration

  • Python 3.12 or newer.
  • Node.js and npm for the provider bridge.
  • ffmpeg available in PATH.
  • openssl available in PATH for AES-128 encrypted HLS segments.
  • pytest is optional; the current regression tests are unittest-compatible and can run with the Python standard library.
  • Docker builds install the locked Node dependencies with npm ci; rebuild the image after dependency updates.

Install Node dependencies once:

npm install

Run locally:

./kaizoku

Then open:

http://127.0.0.1:8421/

Local runs store scheduled watchlist ZIPs in ./backup; Docker uses the /backup mount. Set KAIZOKU_BACKUP_DIR to use another backup directory outside Docker.

For Uptime Kuma or another HTTP availability monitor, use http://IP:PORT/status. GET returns HTTP 200 with OK; HEAD also returns HTTP 200. The endpoint needs no authentication and reports whether Kaizoku's HTTP server is responding. It does not check provider or download health. For a monitor on another machine, bind Kaizoku to a reachable address and set KAIZOKU_ALLOW_REMOTE=1; the normal app and API routes still require configured credentials for remote clients.

For a dashboard, request GET /api/watchlist/homepage?include_downloads=1. The usual watchlist, planned, finished, dropped, and total counts remain, and downloads adds total, running, pending, failed, and a jobs array. downloads.total counts the jobs in these three states. Each job includes id, name, title, status, episodes, mode, provider, and available progress fields such as percent, episode, and message. name is the task name, with title retained for existing dashboard clients. The array lists running, pending, and failed downloads in that order, including live progress for the current job; completed and canceled jobs and Jellyfin handoffs are excluded. Without the query option, the response has the original counts only. This route always requires HTTP Basic auth, even for local requests. It uses the KAIZOKU_AUTH_USERNAME and KAIZOKU_AUTH_PASSWORD supplied to Docker Compose; set both before starting the container. A missing or invalid Basic header receives HTTP 401 with a WWW-Authenticate challenge.

curl -u 'admin:your-password' 'http://IP:PORT/api/watchlist/homepage?include_downloads=1'

Run the local regression tests:

python3 -m unittest -q

Useful environment variables:

  • KAIZOKU_HOST=0.0.0.0
  • KAIZOKU_PORT=8421
  • KAIZOKU_ALLOW_REMOTE=1 to allow non-loopback clients.
  • KAIZOKU_AUTH_USERNAME=admin and KAIZOKU_AUTH_PASSWORD=choose-a-long-random-password for remote access.
  • KAIZOKU_JOB_STDOUT=true to mirror job logs to container or terminal output.
  • KAIZOKU_STATE_ROOT=/path/to/state to move SQLite state, config, thumbnails, sessions, and staging.
  • KAIZOKU_DOWNLOAD_DIR=/downloads for the default library output path.
  • KAIZOKU_REMOTE_PATH_ROOTS=/downloads,/jellyfin/tv,/jellyfin/movies to limit remote filesystem browsing; comma-separated and platform path separators are accepted.
  • KAIZOKU_MODE=sub, KAIZOKU_QUALITY=best, and KAIZOKU_DEBUG=1 for runtime defaults and diagnostics.
  • KAIZOKU_SEGMENT_RETRIES=8, KAIZOKU_SEGMENT_RETRY_DELAY=1.25, KAIZOKU_SEGMENT_RETRY_MAX_DELAY=15, and KAIZOKU_SEGMENT_DOWNLOAD_DELAY=0 to tune retry/backoff and optional pacing behavior for native HLS segment downloads. Retries cover temporary HTTP responses, DNS failures, connection errors, and socket timeouts.
  • KAIZOKU_MEDIA_HTTP_CLIENT=auto to let protected HLS segment fetches fall back from Python HTTP to curl or curl-impersonate after HTTP 403; use curl or urllib to force one client, and KAIZOKU_CURL_BIN=/path/to/curl_chrome142 to prefer a specific curl-compatible binary. Playlist, segment, and encryption-key requests preserve provider CDN session cookies for the duration of the download process.

Back to wiki home