Skip to main content

Syncronizing Pi-hole with Nebula

warning

This guide is in the queue for a video and will be uploaded to the Hake Hardware YouTube channel soon!

Overview​

This guide will walk you through the process of synchronizing Pi-hole with Nebula. This is useful if you have multiple Pi-hole instances and want to keep them all in sync with each other. This guide will be using Docker which is the recommended way to run Nebula-sync. If you want to run Nebula-sync without Docker, please refer to the Nebula-sync documentation

I have a dedicated LXC that runs Portainer which I use to manage all of my Docker applications. I then run each of my Docker applications in a separate LXC or VM (depending on needs). This allows me to easily manage resources and backups, as well as providing a clean separation of applications. Some may prefer to run all their Docker containers on one VM, but I find that this can lead to a lot of clutter and makes it harder to manage resources. This guide should still be useful no matter how you choose to run your Docker applications.

Prerequisites​

  • Proxmox VE 8.0 or later
  • Pi-hole installed (preferably 2 or more)

Installation​

First, we need to create a new LXC container for Nebula-sync. To do this, open up Proxmox and select your Proxmox server. Then click the Shell button at the top right of the Proxmox web interface.

shell

Then navigate to the Docker Helper Script and copy the command to create a new Proxmox VE Docker LXC. Paste the command into the Proxmox shell and hit enter. This will create a new LXC container with Docker installed.

cmd

You should now see a prompt to create a new Docker LXC. Select yes to proceed.

install

Configure LXC​

I always use the advanced settings when using a Helper Script as I typically like to customize the IP address and various other settings. Most of the time the defaults are fine, but I like to have a little more control over the installation process.

Container type​

I recommend leaving the LXC as Unprivileged unless you have a specific reason to use a Privileged container. Unprivileged containers are more secure and are the recommended way to run Docker on Proxmox.

container-type

Root password​

Set and verify the root password for the container.

root

Container ID​

You will then be prompted to set the container ID. Some have specific conventions for this but I typically just use the next available ID.

id

Hostname​

I usually set the hostname to whatever the application is that I am installing. In this case, I will be using nebula-sync. You can set this to whatever you like, but I recommend using something that is easy to remember.

hostname

Resources​

For the resources, I typically leave the defaults which are:

  • Disk Size: 4GB
  • CPU Cores: 2
  • RAM: 2048MiB

This should be sufficient but you can always increase these later if you find that you need more resources.

Network Bridge​

For the network bridge, the default (vmbr0) should be fine. If you are using a different bridge, you can select that here.

bridge

Static IP​

It's important to use a static IP address. I run all my homelab stuff on a specific subnet so I typically set the IP address to something like 192.168.10.X, but you should use whatever subnet you are using.

static

Gateway​

The gateway should be set to the IP address of your router. If you are using a different subnet, make sure to change the gateway accordingly.

gateway

APT-Cacher IP​

I leave APT-Cacher IP blank as I do not use this feature. If you are using APT-Cacher, you can set this here.

apt

IPv6​

I prefer to disable IPv6 as I do not use it. If you are using IPv6, you can leave this enabled.

ipv6

MTU Size​

I leave MTU Size blank as I do not use this feature. If you are using a specific MTU size, you can set this here.

mtu

DNS Search Domain​

I also leave DNS Search Domain blank as I do not use this feature. If you are using a specific DNS search domain, you can set this here.

dns-search-domain

DNS Server IP​

For DNS Server IP, I leave it blank as I want to use the HOST. If you want to use a specific DNS server, you can set this here.

dns-server-ip

MAC Address​

I leave MAC Address blank as I do not use this feature. If you are using a specific MAC address, you can set this here.

mac-address

VLAN​

I do not set a VLAN as I do not use this feature. If you are using a specific VLAN, you can set this here.

vlan

Advanced Tags​

For Advanced Tags I leave the defaults. If you are using a specific tag, you can set this here.

advanced-tags

Root SSH Access​

Leave Root SSH Access as No unless you have a specific reason to enable this.

ssh-access

Verbose Mode​

Leave Verbose Mode as No unless you have a specific reason to enable this. This will give you more information about the installation process, but it is not necessary.

verbose-mode

Install Docker​

Finally, select yes to install Docker.

install-docker

The installation process will begin, monitor the progress in the terminal. There will be a prompt to install Portainer, make sure to type n then when prompted to install the Portainer Agent type y and press enter.

portainer-agent

Complete Installation​

Once the installation is complete, you can close the terminal.

complete

Add Nebula-sync Environment to Portainer​

Now that we have the LXC container created, open up Portainer and navigate to Environments in the left sidebar.

environments

Click on Add Environment.

add-environment

Then select Docker Standalone and then Start Wizard.

wizard

Since the Portainer Agent is already installed, skip to the bottom and enter the Name and Environment address. The Name can be anything you want, but I typically use the name of the LXC container. The Environment address should be the IP address of the LXC container with port 9001 at the end.

settings

Then click Connect. You should see a confirmation toast, and the environment listed as a New Environment.

new-environment

Click Close or go back to the Home tab. You should now see the new environment listed in the Environments section.

environment-section

Configure Pi-hole App password​

Before we can install Nebula-sync, we need to configure the Pi-hole app password. This is used to authenticate with the Pi-hole API. Open up the Pi-hole web interface and navigate to Settings > Web Interface/API.

web-interface

Click the toggle to switch to Expert mode.

toggle

Click the button to Configure App Password. This will generate a new password for the Pi-hole API. Make sure to copy this password as we will need it later.

configure-app-password

Save the password somewhere safe and then click Enable new app password.

app-password

You may receive a warning about needed to re-login after enabling the new app password. This is normal and you can ignore it.

Install Nebula-sync​

Now that we have the environment set up, we can install Nebula-sync. Select the environment you just created by clicking it. Now create a new stack by clicking Stacks in the left sidebar and then Add Stack.

add-stack

A stack is similar to a Docker Compose file, it allows you to define multiple services and their configurations in one place. Give the stack a name, I typically use the name of the application. In this case, I will be using nebula-sync.

Then paste the following code into the Web editor section. This is the Docker Compose file for Nebula-sync. I prefer to use the IP of the Pi-hole instance, however if you are using a domain name, you can use that instead.

---
services:
  nebula-sync:
    image: ghcr.io/lovelaze/nebula-sync:latest
    container_name: nebula-sync
    environment:
    - PRIMARY=http://<IP ADDRESS or DOMAIN>|<PASSWORD>
    - REPLICAS=http://<IP ADDRESS or DOMAIN>|<PASSWORD>
    - FULL_SYNC=true
    - RUN_GRAVITY=true
    - CRON=0 * * * *

My finished stack looks like this:

finished-stack

This will synchronize the my Primary and Replica Pi-hole instances every hour. You can change the CRON value to whatever you like, but I recommend keeping it at least once an hour.

Once you have pasted the code, click Deploy the stack. This will create the Nebula-sync container and start it. Next, open up the logs for nebula-sync by clicking the document icon under Quick Actions.

open-logs

It should look similar to this:

logs

This means that Nebula-sync is running and is synchronizing the Pi-hole instances. You can close the logs now.

Additional Replicas​

If you add additional replicas make sure to add them to the REPLICAS environment variable.

services:
  nebula-sync:
    image: ghcr.io/lovelaze/nebula-sync:latest
    container_name: nebula-sync
    environment:
    - PRIMARY=http://ph1.example.com|password
    - REPLICAS=http://ph2.example.com|password,http://ph3.example.com|password
    - FULL_SYNC=true
    - RUN_GRAVITY=true
    - CRON=0 * * * *

Conclusion​

That's it! You have successfully installed and configured Nebula-sync to synchronize your Pi-hole instances. If you have any questions or run into any issues, feel free to reach out in the Hake Hardware Discord or leave a comment on my YouTube channel. I do periodically check the comments and will do my best to respond to any questions.