Installation | Configuration | Changelog

Orbital Sync

Orbital Sync synchronizes multiple Pi-hole instances for high availability (HA) using the built-in "teleporter". In other words, it performs a "backup" in the Pi-hole admin interface of your primary Pi-hole instance, and then "restores" that backup to any number of "secondary" Pi-holes also via their admin interface. As a result, it supports the synchronization of anything currently supported by Pi-hole's "teleporter". See "Configuration" for the defaults.

Alternatives

I love Gravity Sync and have used it for some time, but I personally find it to be difficult to set up in some contexts (Docker, Unraid, Synology, etc.). Orbital Sync's approach is designed to rely less on the servers running Pi-hole by instead acting on their admin interface just like you would.

Why would I want multiple Pi-holes?

Ever had the server running your Pi-hole go down? Or have you ever needed to perform maintenance on that server? This can obviously be extremely disruptive to anyone using your network. By running multiple Pi-hole instances (replicas) and giving your network clients secondary/tertiary/etc DNS servers, any outage involving one of your Pi-hole instances doesn't bring down your whole network.

Getting Started

Set up your secondary Pi-hole instance(s) just like you did your primary. Once that's done, choose one of the following:

Docker

The following is an example Docker Compose file for running this project. See the configuration section for more environment variables.

version: '3'
services:
  orbital-sync:
    image: mattwebbio/orbital-sync:1
    environment:
      PRIMARY_HOST_BASE_URL: 'https://pihole1.example.com'
      PRIMARY_HOST_PASSWORD: 'your_password1'
      SECONDARY_HOSTS_1_BASE_URL: 'https://pihole2.example.com'
      SECONDARY_HOSTS_1_PASSWORD: 'your_password2'
      SECONDARY_HOSTS_2_BASE_URL: 'http://192.168.1.3'
      SECONDARY_HOSTS_2_PASSWORD: 'your_password3'
      SECONDARY_HOSTS_3_BASE_URL: 'http://server:8080'
      SECONDARY_HOSTS_3_PASSWORD: 'your_password4'
      SECONDARY_HOSTS_3_PATH: '/apps/pi-hole'
      INTERVAL_MINUTES: 60

The Orbital Sync Docker image is published to both DockerHub and the GitHub Package Repository:
mattwebbio/orbital-sync
ghcr.io/mattwebbio/orbital-sync

Distroless images

Distroless images are also available with *-distroless tags; for example, v1 is available as mattwebbio/orbital-sync:1-distroless. These images are slightly larger but are theoretically more secure than the default Alpine-based images, because they're supposed to contain only the Orbital Sync code and its direct dependencies. They do not include a shell, package manager, or other tools that are typically present in a Linux distribution.

Node

As with Docker, running with Node requires you export any required environment variables before running Orbital Sync. See the configuration section for more information.

npm install -g orbital-sync
orbital-sync

Requirements

The admin web interfaces of all Pi-holes must be accessible by the container/server running this service. In other words, they have to be on the same network.

It is recommended you run this service with Docker.

Star History

Disclaimer

This project is not associated with the official Pi-hole project and is a community maintained piece of software. See the license.

Pi-hole is a registered trademark of Pi-hole LLC.

orbital-sync