DDClient Extended

ddclient packaged into a Docker container with a FastAPI-based backend API and optional integragion with healthchecks.io.

     

Features

• Runs ddclient to update dynamic DNS records.
• Exposes a FastAPI-based API to expose execution information.
• Pings healthchecks.io with the status of ddclient runs (see API Endpoints).
• Allows mounting a custom ddclient.conf configuration file.

 

Getting Started

Prerequisites

• Docker
• Docker Compose (optional)

 

Important

The default ddclient.conf file does not contain any valid DNS domain configurations and will result in nothing happening. While the default file can be used for testing, this container is designed to have a custom ddclient.conf file supplied as a mount.

 

With Docker

To run the container using Docker Compose, modify the sample docker-compose.yml file to meet your requirements or create a docker-compose.yml with the following content:

services:
  ddclient-api:
    image: ghcr.io/smith8ca/ddclient-extended:latest
    container_name: ddclient-api
    ports:
      - "8000:8000"
    environment:
      - DDCLIENT_INTERVAL=360m
      - HEALTHCHECKS_URL=YOUR-HC-URL
      - HEALTHCHECKS_ID=YOUR-UUID
    volumes:
      - /path/to/your/ddclient.conf:/tmp/ddclient.conf:ro

To launch with Docker Run:

docker run -d -p 8000:8000 --name ddclient-api \
    -e DDCLIENT_INTERVAL=360m \
    -e HEALTHCHECKS_URL=YOUR-HC-URL \
    -e HEALTHCHECKS_ID=YOUR-UUID \
    -v /path/to/your/ddclient.conf:/tmp/ddclient.conf:ro \
    ghcr.io/smith8ca/ddclient-extended:latest

Be sure to update the environment variables accordingly. See the Environment Variables section for more information.

 

From Source

First, clone the repository:

git clone https://github.com/smith8ca/ddclient-extended.git

Build the Docker image by running the following:

docker build -t ddclient-extended .

 

Self-Signed Certificates

By default, the curl command used to ping healthchecks has the --insecure flag enabled to avoid issues with self-signed certificates typically used in self-hosted environments. Otherwise, the curl commands will fail. You can read more about this behavior here.

If you are self-hosting Healthchecks and you would like the healthcheck pings to communicate over HTTPS, you may supply your Certificate Authority to the container by mounting a custom ca.pem file to /etc/ssl/certs/ca.pem:ro and setting the HEALTHCHECKS_CUSTOM_CA environment variable to true as shown below:

services:
  ddclient-api:
    image: ghcr.io/smith8ca/ddclient-extended:latest
    container_name: ddclient-api
    ports:
      - "8000:8000"
    environment:
      - HEALTHCHECKS_URL=https://example.lan
      - HEALTHCHECKS_ID=YOUR-UUID
      - HEALTHCHECKS_CUSTOM_CA=true
    volumes:
      - /path/to/your/ca.pem:/etc/ssl/certs/ca.pem:ro

This will force the curl command to execute healthcheck pings over HTTPS using your certificate authority.

 

Environment Variables

The following environment variables can be used to configure the Docker container:

Variable	Description	Default	Required
DDCLIENT_INTERVAL	The interval between ddclient runs	360m	No
HEALTHCHECKS_URL	The base URL for healthchecks.io	N/A	No
HEALTHCHECKS_ID	The UUID for the healthchecks.io check	N/A	No
HEALTHCHECKS_CUSTOM_CA	Whether to use a custom certificate authority	false	No

 

API Endpoints

The FastAPI application exposes the following API endpoints:

• GET /last_healthcheck_status: Returns the status of the last health check.
• GET /last_healthcheck_timestamp: Returns the timestamp of the last health check.
• GET /last_update_ip: Returns the IP address of the last ddclient update.
• GET /last_update_status: Returns the status of the last ddclient update.
• GET /last_update_timestamp: Returns the timestamp of the last ddclient update.
• POST /run_ddclient: Manually triggers the ddclient to run once and returns the output.

Accessing the API Documentation

FastAPI automatically generates interactive API documentation. You can access it at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

 

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

Roadmap

To see the project's wishlist for upcoming features and planned improvements, please refer to the ROADMAP.md file.

 

Credits

• ddclient: This project uses ddclient, a Perl client used to update dynamic DNS entries for accounts on various DNS providers.
• FastAPI: This project uses FastAPI, a modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints.
• Healthchecks: This project is built to work with healthchecks, an open-source cron job and background task monitoring service

 

License

This project is licensed under the GNU General Public License v3.0.