Skip to content

Docker

Pre-built images are published to the GitHub Container Registry as ghcr.io/kfmndev/fltr. They are built for linux/amd64 and linux/arm64.

Warning

Since ghcr.io/linuxserver/baseimage-alpine is used as a baseimage, set PUID and PGID to avoid file permission issues. See Understanding PUID and PGID for details.

Start a container

docker run -d \
  --name fltr \
  -p 8080:8080 \
  -v "$PWD/block_rules.json":/config/block_rules.json:ro \
  -e FLTR_ALLOW_UPSTREAM=http://allow.example.com \
  ghcr.io/kfmndev/fltr

This command includes the recommended but optional flags:

  • start the container in the background (-d)
  • give the container a static name (--name)
  • set the explicit port mapping (-p 8080:8080)

Docker Compose

docker-compose.yml
services:
  fltr:
    image: ghcr.io/kfmndev/fltr
    container_name: fltr
    ports:
      - 8080:8080
    environment:
      - FLTR_ALLOW_UPSTREAM=http://allow.example.com
    volumes:
      - ./block_rules.json:/config/block_rules.json:ro
    restart: unless-stopped

Image tags

The image is published under several tags, depending on what triggered the build:

  • Every push to main: fltr:main and fltr:main-<short-sha>, where <short-sha> is the commit's short hash.
  • Every Git version tag (e.g. v1.0.0): fltr:latest, the version split into 1, 1.0, and 1.0.0, and again fltr:main-<short-sha>

Warning

Only use the latest tag when you want to track the most recent release. Pin a specific version to make sure nothing changes unattended.

Healthcheck

The image ships a HEALTHCHECK that probes http://${HOST}:${PORT}/healthz every 30 seconds.

The probe command splits FLTR_ADDR at the last colon using POSIX shell parameter expansion, which linuxserver/baseimage-alpine supports through BusyBox ash. If the address binds all interfaces (:8080, 0.0.0.0:8080, [::]:8080), the fallback is 127.0.0.1.

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD HOST="${FLTR_ADDR%:*}"; PORT="${FLTR_ADDR##*:}"; \
      case "$HOST" in ""|"0.0.0.0"|"::"|"[::]") HOST="127.0.0.1";; esac; \
      wget -q -O /dev/null "http://${HOST}:${PORT}/healthz"
  • :8080 gets split into host 127.0.0.1 and port 8080
  • 0.0.0.0:9090 becomes host 127.0.0.1 and port 9090

If FLTR_ADDR is changed from the default, the probe follows, so the container reports healthy as long as fltr answers on the address it was told to serve.

To check the health status while the container is running (assuming fltr as its name), use this:

$ docker inspect --format '{{.State.Health.Status}}' fltr
healthy