cplieger/docker-fclones-scheduler repository overview

⁠docker-fclones-scheduler

Find and deduplicate files on a schedule, reclaiming wasted disk space automatically.

⁠What it does

Wraps the fclones duplicate file finder in a Go scheduler daemon with interval-based scheduling and a CLI health probe. Supports the group, link, remove, and dedupe actions with configurable arguments. Reports scan statistics including duplicates found, space reclaimable, and files processed. All output goes to stdout/stderr for collection by log aggregators (Alloy, Promtail, etc.) and alerting via Grafana or similar.

• Mount your media directory and schedule periodic scans; fclones finds duplicates and can replace them with hardlinks or remove them entirely
• Built-in scheduler, or hand scheduling to an external scheduler (cron, Ofelia, etc.) via the scan subcommand
• Built-in Docker healthcheck with automatic recovery

⁠Why this design

• Scheduler your way: ships with a self-contained interval scheduler, so no external cron, systemd timer, or orchestrator-level scheduling is needed. If you already run a central scheduler (Ofelia, cron), set SCAN_INTERVAL=off and trigger scans with docker exec fclones /app/wrapper scan instead
• One owner for every run: the daemon executes every scan, serialized in one queue, so every run's logs land on the container's own log stream in both scheduling modes and the same alert rules work everywhere
• Machine-readable report contract: the scan consumes fclones' JSON report with a strict decoder, so an upstream output-format change fails the run loudly instead of silently zeroing the duplicate stats your alerting reads
• Distroless and rootless: runs as nonroot (UID 65532) on gcr.io/distroless/static-debian13 with no shell or package manager
• Dangerous flags blocked by default: --transform, --in-place, and --no-copy are rejected unless you explicitly opt in with ALLOW_UNSAFE_ARGS=true, preventing command injection via environment variables
• Structured logs: logfmt with UTC timestamps, so log lines are zone-stable regardless of the container's TZ and alerting needs no custom exporter

⁠Pull

docker pull cplieger/docker-fclones-scheduler:latest

Also published to ghcr.io/cplieger/docker-fclones-scheduler with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for docker-fclones-scheduler. See the README for all configuration options and hardening.
services:
  fclones:
    image: ghcr.io/cplieger/docker-fclones-scheduler:latest
    container_name: fclones
    restart: unless-stopped
    # Override with PUID/PGID in .env; defaults to 1000:1000.
    user: "${PUID:-1000}:${PGID:-1000}"  # match your host user

    environment:
      SCAN_INTERVAL: "1h"  # Go duration; "off" = external trigger, "0" = run once; see README "Scheduling modes"
      FCLONES_SCAN_PATHS: "/scandir"  # must match a volume mount target below
      FCLONES_ARGS: "--rf-over 1"
      FCLONES_ACTION: "link"  # group (report), link (hardlink), remove (delete), or dedupe (reflink)
      FCLONES_ACTION_ARGS: "--priority bottom"

    volumes:
      - "/path/to/media:/scandir"  # link/remove/dedupe modify files here (don't mount :ro for those)
      - "/opt/appdata/fclones:/cache"  # write-probed at startup; container exits if /cache isn't writable

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Contributing⁠
• Releases and changelog⁠

⁠License

Apache-2.0. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/.

The image packages fclones⁠ (MIT) at the version pinned by FCLONES_VERSION in the Dockerfile: amd64 downloads and unpacks the upstream release tarball https://github.com/pkolaczk/fclones/releases/download/<tag>/fclones-<version>-linux-musl-x86_64.tar.gz, arm64 builds that same tag from source at a pinned commit. The build applies no patches, so this repository's Dockerfile plus the upstream sources it names is the complete recipe for the fclones binary the image ships. The license texts of the Rust crates compiled into the amd64 binary are kept under licenses/crates/ in this repository, regenerated by scripts/vendor-crate-licenses.sh.