flaresolverr-adapter

Production-ready containerized Flaresolverr adapter for the Suwayomi/Comix manga-server stack.

This replaces the prior host-mounted /root/suwayomi_flaresolverr_adapter.py deployment pattern with a versioned source repository, tests, Dockerfile, GitHub Actions build, and immutable GHCR image tags.

Behavior

The adapter listens on /v1 and forwards Flaresolverr-compatible JSON requests to ADAPTER_UPSTREAM (default http://127.0.0.1:8191). It preserves the staging-validated bounded behavior from Kanban task t_dbbf7ad6:

• bounded solve concurrency with a semaphore (ADAPTER_MAX_CONCURRENCY, default 1)
• bounded queue wait (ADAPTER_QUEUE_TIMEOUT_SECONDS, default 5)
• controlled busy response: HTTP 503 with adapter_busy=true
• outbound maxTimeout clamp (ADAPTER_MAX_TIMEOUT_MS, default 120000)
• no synthetic adapter-retry-* sessions; sessionless retries let Flaresolverr quit temporary drivers normally
• controlled upstream timeout/error responses: HTTP 504 or 502
• /health reports limits, version, upstream, and counters

Runtime configuration

Variable	Default	Purpose
ADAPTER_VERSION	dev	Version string surfaced in /health. CI sets this to the commit SHA.
ADAPTER_LISTEN_HOST	127.0.0.1	Listen address. Keep loopback when sharing network_mode: service:proxy-transparent.
ADAPTER_LISTEN_PORT	8192	Listen port.
ADAPTER_UPSTREAM	http://127.0.0.1:8191	Flaresolverr base URL.
ADAPTER_MAX_CONCURRENCY	1	Concurrent solve limit.
ADAPTER_QUEUE_TIMEOUT_SECONDS	5	How long extra requests wait before HTTP 503.
ADAPTER_MAX_TIMEOUT_MS	120000	Upper clamp for forwarded Flaresolverr maxTimeout.
ADAPTER_MIN_TIMEOUT_MS	1000	Lower clamp for forwarded Flaresolverr maxTimeout.
ADAPTER_ATTEMPTS	2	Attempts per request. Retries remain sessionless unless caller supplied a session.
ADAPTER_CLIENT_TIMEOUT_PAD_SECONDS	15	Extra seconds on the Python HTTP client timeout.

Development

python3 -m unittest discover -s tests -v
docker build -t flaresolverr-adapter:test .
docker run --rm -p 8192:8192 -e ADAPTER_LISTEN_HOST=0.0.0.0 flaresolverr-adapter:test

Image publishing

GitHub Actions publishes:

• ghcr.io/singgihanggana/flaresolverr-adapter:sha-<short-commit>
• ghcr.io/singgihanggana/flaresolverr-adapter:latest on main
• ghcr.io/singgihanggana/flaresolverr-adapter:<git-tag> for v* tags

Production/staging Portainer stacks should use an immutable sha-<short-commit> tag or digest, not latest.

Portainer compose replacement pattern

Replace the dirty host-mounted adapter service:

  flaresolverr-adapter:
    image: ghcr.io/flaresolverr/flaresolverr:latest
    volumes:
      - /root/suwayomi_flaresolverr_adapter.py:/adapter/flaresolverr_adapter.py:ro
    command: ["python3", "/adapter/flaresolverr_adapter.py"]

with the image-based service:

  flaresolverr-adapter:
    image: ghcr.io/singgihanggana/flaresolverr-adapter:sha-<short-commit>
    container_name: flaresolverr-adapter
    restart: unless-stopped
    network_mode: service:proxy-transparent
    environment:
      - ADAPTER_VERSION=sha-<full-commit>
      - ADAPTER_UPSTREAM=http://127.0.0.1:8191
      - ADAPTER_MAX_CONCURRENCY=1
      - ADAPTER_QUEUE_TIMEOUT_SECONDS=5
      - ADAPTER_MAX_TIMEOUT_MS=120000
      - ADAPTER_ATTEMPTS=2
    healthcheck:
      test:
        - CMD-SHELL
        - python3 -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8192/health', timeout=5).read()" || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    depends_on:
      flaresolverr:
        condition: service_healthy
      proxy-transparent:
        condition: service_started

Keep comix-browser-sidecar pinned to ghcr.io/singgihanggana/comix-browser-sidecar:sha-576b846 unless a separately verified sidecar release replaces it.