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.

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.

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.

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

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_HOST_1_BASE_URL: 'https://pihole2.example.com'
      SECONDARY_HOST_1_PASSWORD: 'your_password2'
      SECONDARY_HOST_2_BASE_URL: 'http://192.168.1.3'
      SECONDARY_HOST_2_PASSWORD: 'your_password3'
      SECONDARY_HOST_3_BASE_URL: 'http://server:8080'
      SECONDARY_HOST_3_PASSWORD: 'your_password4'
      SECONDARY_HOST_3_PATH: '/apps/pi-hole'
      INTERVAL_MINUTES: 30

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

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

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.

Secondary hosts must be sequential (SECONDARY_HOST_1_BASE_URL, SECONDARY_HOST_2_BASE_URL, SECONDARY_HOST_3_BASE_URL, and so on) and start at number 1. Any gaps (for example, 3 to 5 skipping 4) will result in hosts after the gap being skipped in the sync process.

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.