cplieger/docker-fclones-scheduler repository overview

⁠docker-fclones-scheduler

docker-fclones-scheduler runs the fclones⁠ duplicate finder on a schedule, in a rootless container, and replaces the copies it finds with hardlinks or removes them. It has no web page and writes its results to its log.

⁠What it does

docker-fclones-scheduler gets back the disk space that duplicate files take, with no cron job to write:

• Scans your folders on the interval you set, 3 hours by default, or when your scheduler asks.
• Replaces each extra copy with a hardlink or a copy-on-write clone, deletes it, or only reports it.
• Logs each duplicate it found, up to 500 pairs per scan, and the space it freed.
• Marks itself unhealthy when a scan fails or an action changes no duplicate, until the next good scan.

⁠Who it is for

docker-fclones-scheduler is built for a media library or a file share on an always-on Linux machine with Docker, where the same file can land in several folders. It checks every setting before the first scan and, by default, refuses fclones options that run commands. You need a folder the container's user can write to, and hardlinks need the copies on one filesystem.

Two other projects suit a different setup:

• Consider fclones-gui⁠ if you want to pick by hand, in a desktop window, which copies to remove. It is the fclones author's interactive frontend.
• Consider Krokiet⁠ if you also want to find similar images, similar videos or music duplicates, in a desktop app.

docker-fclones-scheduler is free software under the Apache-2.0 license.

⁠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 docs/configuration.md and docs/hardening.md for all configuration options and hardening.
services:
  fclones:
    image: ghcr.io/cplieger/docker-fclones-scheduler:latest
    container_name: fclones
    restart: unless-stopped
    # Run "sudo mkdir -p /opt/appdata/fclones && sudo chown 1000:1000 /opt/appdata/fclones"
    # before the first start, or the container exits. If .env sets PUID and PGID, use those numbers.
    user: "${PUID:-1000}:${PGID:-1000}"

    environment:
      SCAN_INTERVAL: "1h"  # or 30m, 12h. "off" waits for an outside trigger and "0" scans once
      FCLONES_SCAN_PATHS: "/scandir"  # must match a volume target below
      FCLONES_ARGS: "--rf-over 1"  # report files that have more than one copy
      FCLONES_ACTION: "link"  # group only reports, link replaces copies with hardlinks, remove deletes them, dedupe uses reflinks
      FCLONES_ACTION_ARGS: "--priority bottom"  # keep the first copy fclones lists, replace the others

    volumes:
      - "/path/to/media:/scandir"  # link, remove and dedupe change files here, so this user must be able to write to it
      - "/opt/appdata/fclones:/cache"  # the container exits at start if this user cannot write here

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How docker-fclones-scheduler works⁠
• Monitoring and alerts⁠
• 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_REF 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.