nebula-sync

Run nebula-sync using a single Docker command by passing configuration through -e flags.

docker run --rm \
  --name nebula-sync \
  -e PRIMARY="http://ph1.example.com|password" \
  -e REPLICAS="http://ph2.example.com|password" \
  -e FULL_SYNC=true \
  -e RUN_GRAVITY=true \
  ghcr.io/lovelaze/nebula-sync:latest

You can install nebula-sync as a Linux/OSX binary or via Docker.

To build from source using Go:

go install github.com/lovelaze/nebula-sync@latest

To run the binary directly:

# Standard run
nebula-sync run

# Run using environment variables from a specific file
nebula-sync run --env-file .env

Docker Compose is the recommended method for deployment. Use the ghcr.io/lovelaze/nebula-sync:latest image and provide configuration via environment variables.

Example docker-compose.yml:

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 * * * *

The following environment variables must be provided for nebula-sync to function:

Note: For Docker users, PRIMARY and REPLICAS can be provided via Docker secrets using PRIMARY_FILE and REPLICAS_FILE respectively.

By default, the nebula-sync Docker container runs as user 1001. If you are using Docker secrets, the container user must have read permissions for the secret files. If you encounter the error Failed to initialize service error="open /run/secrets/primary: permission denied", you must resolve the permission mismatch using one of these two methods:

1. Adjust file permissions: Ensure the secret files are owned by user 1001 and have appropriate read permissions:

   chown 1001 ./your/secretfiles && chmod 400 ./your/secretfiles

2. Change the container user: Use the user directive in your Docker Compose file to run the container as a different user, then ensure your secret files are owned by that specific user.

You can retrieve and update the Pi-hole configuration using the following methods:

• GetConfig(): Returns a *model.ConfigResponse containing the current configuration.
• PatchConfig(patchRequest *model.PatchConfigRequest): Sends a patch request to update specific configuration settings.

Both methods require a valid authenticated session.

Teleporter is used for full configuration backups and restores. The Client interface provides:

• GetTeleporter() ([]byte, error): Downloads the current Teleporter backup as a byte slice (typically a .zip file).
• PostTeleporter(payload []byte, teleporterRequest *model.PostTeleporterRequest) error: Uploads a new Teleporter backup. The payload should be the raw bytes of the backup file (e.g., config.zip). You can optionally provide a *model.PostTeleporterRequest to include import metadata via a multipart form field named import.