cplieger/docker-keepalived repository overview

⁠docker-keepalived

Run keepalived⁠ (VRRP failover / high availability) in a container. Bring your own keepalived.conf.

⁠What it does

keepalived⁠ implements VRRP, so two or more machines share a virtual IP with automatic failover: one node owns the VIP, and another takes over within seconds if it dies.

This image is a minimal Alpine wrapper around upstream keepalived, compiled from a pinned upstream source release. There's no entrypoint magic, no env-var-to-config translation, no bundled scripts: you mount your own keepalived.conf and any track / notify scripts it references, and keepalived runs as PID 1. The image also ships keepalived's genhash digest helper for HTTP_GET checker configuration.

⁠Why this design

• Generic upstream-only: no custom track scripts baked in, so the image works for any VRRP topology without inheriting someone else's check logic
• Bind-mount only: all configuration arrives through one read-only :ro mount of /etc/keepalived, and the published example adds no writable bind mounts
• No PID 1 wrapper: keepalived --dont-fork runs as PID 1 directly, so SIGTERM from docker stop reaches it instantly

⁠Pull

docker pull cplieger/docker-keepalived:latest

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

⁠Quick start

# Example compose for docker-keepalived. See the README for all configuration options and hardening.
services:
  keepalived:
    image: ghcr.io/cplieger/docker-keepalived:latest
    container_name: keepalived
    restart: unless-stopped

    # VRRP multicast on a real LAN interface needs host networking + raw-socket/admin caps.
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW

    # If the conf sets enable_script_security, the mount must be root-owned and not group- or
    # world-writable, else keepalived logs "Unsafe permissions found" and disables the scripts.
    # See README "enable_script_security".
    volumes:
      - "./keepalived:/etc/keepalived:ro"

⁠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 Alpine packages in the image ship no license file upstream, so their license texts are kept under licenses/ in this repository and copied in.

The bundled component is keepalived itself, which is GPL-2.0-or-later. The build fetches the pinned release tarball https://www.keepalived.org/software/keepalived-2.4.3.tar.gz (KEEPALIVED_VERSION=v2.4.3), verifies its SHA256, and applies one checked-in patch, patches/0001-report-a-script-that-could-not-be-executed.patch⁠, which is a local modification with no upstream commit behind it and is therefore part of the source the shipped binary is built from. keepalived's own COPYING travels in the image at /usr/share/licenses/keepalived/COPYING, and the upstream project is acassen/keepalived⁠. That tarball, this repository's Dockerfile and the files in patches/ are the complete recipe for the binary in the image, which is how anyone who receives it gets the corresponding source.

patches/ is an exception. It holds a modification to keepalived's own source, so that file stays GPL-2.0-or-later under upstream's terms. Its header states what it changes and the condition for removing it.