Quickstart

You’ll set up ddup to manage one domain, app.example.com, served by two web servers. When one of the servers stops responding, ddup removes its IP from DNS, and adds it back when the server recovers.

Prerequisites#

• A DNS zone hosted by one of the supported DNS providers, and API credentials for it. Each provider’s page explains how to create them.
• Two or more servers with a URL that ddup can request to check their health. It must return a 2xx status code when the server is healthy (you can change the status code).
• Docker or Podman. To run ddup without containers, see Installation.

Step 1: Create the configuration file#

Create a folder for the configuration:

mkdir -p $HOME/.ddup

In that folder, create a file named config.yaml, replacing the IPs and URLs with the ones of your servers:

# How often to check the endpoints
interval: 30s

domains:
  - recordName: "app.example.com"
    # Name of the provider, defined in the "providers" section below
    provider: "my-dns"
    endpoints:
      - name: "web1"
        url: "http://192.0.2.10/healthz"
        ip: "192.0.2.10"
      - name: "web2"
        url: "http://192.0.2.11/healthz"
        ip: "192.0.2.11"

# Enable the dashboard
server:
  enabled: true
  # Needed to reach the dashboard from outside the container
  bind: "0.0.0.0"

Then add a providers section at the end of the file, with the settings for your DNS provider:

providers:
  my-dns:
    awsRoute53:
      hostedZoneId: "Z0123456789ABCDEFGHIJ"
      accessKeyId: "your-access-key-id"
      secretAccessKey: "your-secret-access-key"

providers:
  my-dns:
    azure:
      subscriptionId: "00000000-0000-0000-0000-000000000000"
      resourceGroupName: "my-dns-rg"
      zoneName: "example.com"
      tenantId: "00000000-0000-0000-0000-000000000000"
      clientId: "00000000-0000-0000-0000-000000000000"
      clientSecret: "your-client-secret"

providers:
  my-dns:
    cloudflare:
      apiToken: "your-api-token"
      zoneId: "your-zone-id"

providers:
  my-dns:
    googleCloudDns:
      projectId: "my-project"
      managedZone: "example-com"
      # The key file, in the same folder as config.yaml
      credentialsFile: "/etc/ddup/ddup-key.json"

providers:
  my-dns:
    ovh:
      apiKey: "your-application-key"
      apiSecret: "your-application-secret"
      consumerKey: "your-consumer-key"
      zoneName: "example.com"

Step 2: Start ddup#

# For Podman, replace "docker" with "podman"
docker run -d \
  --name ddup \
  --read-only \
  --restart unless-stopped \
  -v $HOME/.ddup:/etc/ddup:ro \
  -p 127.0.0.1:7401:7401 \
  ghcr.io/italypaleale/ddup:v0

The -p flag makes the dashboard available on port 7401 of your machine, only from the machine itself. The dashboard has no authentication, so don’t expose it on a network you don’t trust.

Step 3: Check that it works#

ddup checks all endpoints as soon as it starts. Look at its logs:

docker logs -f ddup

For each domain, you should see a line with the message Updated DNS records, which lists the IPs that ddup published. If the records already matched, the message is DNS records already up to date instead. If something is wrong, such as invalid credentials, the logs show the error.

Open http://localhost:7401 in a browser to see the dashboard, and look up the domain to see the records:

dig +short app.example.com

Step 4: Try a failover#

Stop the web server on one of the machines. By default, ddup removes an endpoint after it fails 2 checks in a row, so with a 30-second interval its IP disappears from DNS within about a minute. The logs show Endpoint health check failed for each failed check, then Updated DNS records with the remaining IPs.

Start the web server again. On the next check, ddup adds its IP back.

Next steps#

• Installation: run ddup with Docker Compose, or as a service without containers
• Configuration: every configuration option
• Health checks: control how endpoints are checked, and how quickly they’re removed and added back
• Failover with priorities: keep backup servers out of DNS until the main ones fail