{"id":23900112,"url":"https://github.com/primus852/traefik-ddns","last_synced_at":"2026-04-13T22:34:25.283Z","repository":{"id":270823885,"uuid":"911518419","full_name":"primus852/traefik-ddns","owner":"primus852","description":"This repository provides configuration files and instructions for setting up a Cloudflare Dynamic DNS (DDNS) service and a Traefik reverse proxy with Let's Encrypt SSL/TLS support. It includes Docker Compose configurations, environment variable templates, and detailed usage instructions to automate DNS updates and manage SSL certificates.","archived":false,"fork":false,"pushed_at":"2025-05-18T17:44:44.000Z","size":420,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-18T18:35:55.843Z","etag":null,"topics":["cloudflare","ddns","docker","docker-compose","letsencrypt","ssl-tls","traefik"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/primus852.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-03T07:53:31.000Z","updated_at":"2025-05-18T17:44:47.000Z","dependencies_parsed_at":"2025-01-03T11:26:36.661Z","dependency_job_id":"67290d3a-258d-4a35-beb8-b9e8b4c2f0e0","html_url":"https://github.com/primus852/traefik-ddns","commit_stats":null,"previous_names":["primus852/traefik-ddns"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/primus852/traefik-ddns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus852%2Ftraefik-ddns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus852%2Ftraefik-ddns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus852%2Ftraefik-ddns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus852%2Ftraefik-ddns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/primus852","download_url":"https://codeload.github.com/primus852/traefik-ddns/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus852%2Ftraefik-ddns/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260301968,"owners_count":22988715,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","ddns","docker","docker-compose","letsencrypt","ssl-tls","traefik"],"created_at":"2025-01-04T19:14:33.486Z","updated_at":"2026-04-13T22:34:20.237Z","avatar_url":"https://github.com/primus852.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Cloudflare DDNS and Traefik Configuration\n\nThis repository contains configuration files and instructions for setting up a Cloudflare Dynamic DNS (DDNS) service and a Traefik reverse proxy with Let's Encrypt SSL/TLS support.\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Requirements](#requirements)\n3. [Configuration Files](#configuration-files)\n    - [config.ddns.json](#configddnsjson)\n    - [compose.yml](#composeyml)\n    - [.env.dist](#envdist)\n    - [acme.json](#acmejson)\n4. [Usage](#usage)\n    - [Environment Variables](#environment-variables)\n    - [Running the Services](#running-the-services)\n5. [Dashboard Access](#dashboard-access)\n6. [Updating Configuration](#updating-configuration)\n7. [Troubleshooting](#troubleshooting)\n8. [Makefile Usage](#makefile-usage)\n8. [Maintenance and Updates](#maintenance-and-updates)\n9. [Security Considerations](#security-considerations)\n10. [Support](#support)\n\n---\n\n## Overview\n\nThis setup provides:\n\n- **Dynamic DNS updates**: Automatically updates A and AAAA records in Cloudflare.\n- **Reverse proxy management**: Handles routing and SSL/TLS certificates with Traefik.\n- **Automatic SSL certificate renewal**: Uses Let's Encrypt with DNS-01 challenges.\n\n---\n\n## Requirements\n\n- Docker and Docker Compose installed.\n- A Cloudflare account with an API token that has DNS edit permissions.\n- Domain names managed through Cloudflare.\n\n---\n\n## Configuration Files\n\n### `config.ddns.json`\n\nConfigures the Cloudflare DDNS updater.\n\n```json\n{\n  \"cloudflare\": [\n    {\n      \"authentication\": {\n        \"api_token\": \"your-cloudflare-api-token\"\n      },\n      \"zone_id\": \"your-cloudflare-zone-id\",\n      \"subdomains\": [\n        {\n          \"name\": \"*.your-subdomain\",\n          \"proxied\": false\n        }\n      ]\n    }\n  ],\n  \"a\": true,\n  \"aaaa\": true,\n  \"purgeUnknownRecords\": true,\n  \"ttl\": 300\n}\n```\n\n- **`zone_id`**: The Cloudflare zone identifier for your domain.\n- **`subdomains`**: List of subdomains to update dynamically.\n\n### `compose.yml`\n\nDefines Docker Compose services for DDNS and Traefik.\n\n```yaml\nservices:\n  ddns:\n    image: timothyjmiller/cloudflare-ddns:latest\n    container_name: ddns\n    network_mode: 'host'\n    environment:\n      - PUID=1000\n      - PGID=1000\n    volumes:\n      - ./config.ddns.json:/config.json:ro\n    restart: unless-stopped\n\n  traefik:\n    image: traefik:latest\n    container_name: traefik\n    ports:\n      - \"80:80\"\n      - \"443:443\"\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock:ro\n      - ./certs:/letsencrypt\n    command:\n      - \"--api=true\"\n      - \"--api.dashboard=true\"\n      - \"--entrypoints.web.address=:80\"\n      - \"--entrypoints.websecure.address=:443\"\n      - \"--certificatesresolvers.letsencrypt.acme.dnschallenge=true\"\n      - \"--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json\"\n      - \"--certificatesResolvers.letsencrypt.acme.dnschallenge.provider=cloudflare\"\n      - \"--certificatesResolvers.letsencrypt.acme.dnschallenge.resolvers=1.1.1.1:53,1.0.0.1:53\"\n    environment:\n      - CF_DNS_API_TOKEN=${CF_DNS_API_TOKEN}\n      - CERT_MAIL=${CERT_MAIL}\n    restart: unless-stopped\n```\n\n### `.env.dist`\n\nA template environment file for storing sensitive variables.\n\n```env\n# Cloudflare\nCF_DNS_API_TOKEN=your-cloudflare-api-token\nCERT_MAIL=your-email@example.com\n\n# Let's Encrypt\nMAIN_DOMAIN=your-main-domain.com\nSANS_DOMAIN=*.your-main-domain.com\n\n# Dashboard\nDASHBOARD_DOMAIN=traefik.localhost\nDASHBOARD_ENABLED=true\n\n# WhoAmI Sample\nWHOAMI_DOMAIN=whoami.localhost\n```\n\n- **`CF_DNS_API_TOKEN`**: Your Cloudflare API token with DNS permissions.\n- **`CERT_MAIL`**: Email address for Let's Encrypt notifications.\n- **`MAIN_DOMAIN`**: The primary domain for the SSL certificate.\n- **`SANS_DOMAIN`**: Additional domains (wildcards) for the SSL certificate.\n- **`DASHBOARD_ENABLED`**: Enable Traefik dashboard (default: `false`).\n- **`DASHBOARD_DOMAIN`**: URL of the traefik dashboard, if `DASHBOARD_ENABLED=true`\n- **`WHOAMI_DOMAIN`**: URL of the whoami service, for demo purposes\n\n### `acme.json`\n\nThis file stores SSL/TLS certificates managed by Traefik. Will be created automatically. Ensure it has restricted permissions after creation:\n\n```bash\nchmod 600 acme.json\n```\n\n---\n\n## Usage\n\n### Environment Variables\n\n1. Copy `.env.dist` to `.env`:\n\n   ```bash\n   cp .env.dist .env\n   ```\n\n2. Edit `.env` to provide the required values.\n\n### Running the Services\n\n1. Start the Docker Compose services:\n\n   ```bash\n   docker-compose up -d\n   ```\n\n2. Check if the services are running:\n\n   ```bash\n   docker ps\n   ```\n\n---\n\n## Dashboard Access\n\n1. Ensure Traefik's dashboard is enabled in the `compose.yml` file under the `command` section.\n2. Visit the dashboard using your domain:\n\n   ```\n   https://your-domain/dashboard\n   ```\n\n---\n\n## Updating Configuration\n\n### For `config.ddns.json`\n\n- Modify the subdomains or zone ID.\n- Restart the DDNS service:\n\n  ```bash\n  docker-compose restart ddns\n  ```\n\n### For `compose.yml`\n\n- Make necessary updates to the services or environment variables.\n- Rebuild and restart:\n\n  ```bash\n  docker-compose up -d --build\n  ```\n\n---\n\n## Troubleshooting\n\n### DNS Updates Not Reflecting\n\n- Verify the API token and `zone_id` in `config.ddns.json`.\n- Check DDNS logs:\n\n  ```bash\n  docker logs ddns\n  ```\n\n### SSL Certificates Not Issued\n\n- Ensure DNS records are correctly set up.\n- Check Traefik logs:\n\n  ```bash\n  docker logs traefik\n  ```\n\n---\n\n## Makefile Usage\nThe `Makefile` provides convenient commands to manage the Docker Compose services. Below are the available targets and their usage:  \n\n### Targets\n- `start-ddns`: Starts the Cloudflare DDNS service.\n- `start-traefik`: Starts the Traefik service.\n- `start`: Starts both the DDNS and Traefik services, including whoami sample.\n- `start-dev`: Starts both the DDNS and Traefik services\n- `stop`: Stops all running services.\n- `down`: Stops and removes all services.\n\n### Usage\nTo use the `Makefile` targets, run the following commands in your terminal:  \n  \n`make \u003ctarget\u003e`, e.g., `make start` to start both services and the sample application.\n\n### Production Usage\nTo start the services in production mode, use `ENV=prod make \u003ctarget\u003e`\n\n## Maintenance and Updates\n\n### Updating Docker Images\n\n1. Pull the latest images:\n\n   ```bash\n   docker-compose pull\n   ```\n\n2. Restart the services:\n\n   ```bash\n   docker-compose up -d\n   ```\n\n### Backing Up Configuration\n\n- Backup important files:\n  - `.env`\n  - `config.ddns.json`\n  - `acme.json`\n  - `compose.yml`\n\n---\n\n## Security Considerations\n\n- **File Permissions**: Restrict access to sensitive files like `.env`, `config.ddns.json`, and `acme.json`.\n- **API Tokens**: Use scoped API tokens with minimal permissions.\n- **Regular Updates**: Keep Docker images and configurations up-to-date.\n\n---\n\n## Support\n\nFor support:\n\n- Open an issue on the repository.\n- Refer to [Traefik Documentation](https://doc.traefik.io/traefik/).\n- Refer to [Cloudflare API Documentation](https://developers.cloudflare.com/api/).\n\n---\n\n## Cloudflare Setup\n\n### Sample config.ddns.json\n\n```json\n{\n  \"cloudflare\": [\n    {\n      \"authentication\": {\n        \"api_token\": \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n      },\n      \"zone_id\": \"XXXXXXXXXXXXXXXX\",\n      \"subdomains\": [\n        {\n          \"name\": \"*.dev\",\n          \"proxied\": false\n        }\n      ]\n    }\n  ],\n  \"a\": true,\n  \"aaaa\": true,\n  \"purgeUnknownRecords\": true,\n  \"ttl\": 300\n}\n```\n\nleading to the following DNS records:\n![cf_setup.png](images/cf_setup.png)\n\n### API Token\nThe Cloudflare API token can be obtained from the Cloudflare dashboard under `My Profile` -\u003e `API Tokens` -\u003e `Create Token`.\n(https://dash.cloudflare.com/profile/api-tokens)\n![cf_token.png](images/cf_token.png)\n\n### Zone ID\nThe zone ID can be found in the Cloudflare dashboard under the domain's `Overview` tab.\n![cf_zone_id.png](images/cf_zone_id.png)\n\n\nFeel free to contribute or suggest improvements!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimus852%2Ftraefik-ddns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprimus852%2Ftraefik-ddns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimus852%2Ftraefik-ddns/lists"}