chuck1041/ddclient-extended repository overview

⁠

⁠ 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)

⁠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:

⁠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⁠.