Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mattwebbio/orbital-sync
Synchronize multiple Pi-hole instances
https://github.com/mattwebbio/orbital-sync
docker node pi-hole pihole replication sync typescript
Last synced: 7 days ago
JSON representation
Synchronize multiple Pi-hole instances
- Host: GitHub
- URL: https://github.com/mattwebbio/orbital-sync
- Owner: mattwebbio
- License: mit
- Created: 2022-08-26T01:58:24.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-10-28T02:36:15.000Z (11 days ago)
- Last Synced: 2024-10-30T14:06:45.153Z (8 days ago)
- Topics: docker, node, pi-hole, pihole, replication, sync, typescript
- Language: TypeScript
- Homepage: http://orbitalsync.com
- Size: 2.68 MB
- Stars: 664
- Watchers: 5
- Forks: 21
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://orbitalsync.com)
[](https://github.com/mattwebbio/orbital-sync)
[](https://github.com/mattwebbio/orbital-sync)
[Installation](https://orbitalsync.com/#getting-started) | [Configuration](https://orbitalsync.com/CONFIG.html) | [Changelog](CHANGELOG.md)
# Orbital Sync
[](https://github.com/mattwebbio/orbital-sync/actions/workflows/ci.yml?query=branch%3Amaster)
[](https://app.codecov.io/gh/mattwebbio/orbital-sync/)
[](CHANGELOG.md)
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](https://orbitalsync.com/CONFIG.html)" for the defaults.
### Alternatives
I love [Gravity Sync](https://github.com/vmstan/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
[](https://hub.docker.com/r/mattwebbio/orbital-sync)
[](https://hub.docker.com/r/mattwebbio/orbital-sync)
The following is an example Docker Compose file for running this project. See the
[configuration](https://orbitalsync.com/CONFIG.html) section for more environment variables.
```yaml
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](https://hub.docker.com/r/mattwebbio/orbital-sync)
[ghcr.io/mattwebbio/orbital-sync](https://github.com/mattwebbio/orbital-sync/pkgs/container/orbital-sync)
Distroless images
[Distroless images](https://github.com/GoogleContainerTools/distroless/blob/main/README.md) 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
[](https://www.npmjs.com/package/orbital-sync)
As with Docker, running with Node requires you export any required environment variables before running Orbital Sync. See the
[configuration](https://orbitalsync.com/CONFIG.html) section for more information.
```shell
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
[](https://star-history.com/#mattwebbio/orbital-sync&Date)
## Disclaimer
[](LICENSE)
This project is not associated with the [official Pi-hole project](https://github.com/pi-hole) and is a community
maintained piece of software. See the [license](LICENSE).
Pi-hole is a [registered trademark](https://pi-hole.net/trademark-rules-and-brand-guidelines/) of Pi-hole LLC.