mattwebbio/orbital-sync repository overview

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⁠

⁠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.