{"id":13582484,"url":"https://github.com/wernerfred/docker-dyndns","last_synced_at":"2025-12-30T04:23:09.938Z","repository":{"id":50692075,"uuid":"185584577","full_name":"wernerfred/docker-dyndns","owner":"wernerfred","description":"Host your own dyndns server with docker!","archived":false,"fork":false,"pushed_at":"2020-12-02T09:06:38.000Z","size":67,"stargazers_count":15,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-05T22:41:34.740Z","etag":null,"topics":["api","dns-configuration","docker","dyndns","dyndns-server","fritzbox","golang","nameserver","selfhosted"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wernerfred.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-08T10:29:46.000Z","updated_at":"2024-02-04T10:35:36.000Z","dependencies_parsed_at":"2022-09-13T11:11:58.845Z","dependency_job_id":null,"html_url":"https://github.com/wernerfred/docker-dyndns","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wernerfred%2Fdocker-dyndns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wernerfred%2Fdocker-dyndns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wernerfred%2Fdocker-dyndns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wernerfred%2Fdocker-dyndns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wernerfred","download_url":"https://codeload.github.com/wernerfred/docker-dyndns/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247495771,"owners_count":20948106,"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":["api","dns-configuration","docker","dyndns","dyndns-server","fritzbox","golang","nameserver","selfhosted"],"created_at":"2024-08-01T15:02:45.619Z","updated_at":"2025-12-30T04:23:09.883Z","avatar_url":"https://github.com/wernerfred.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"![GitHub Workflow Status](https://img.shields.io/github/workflow/status/wernerfred/docker-dyndns/Build%20+%20push%20to%20DockerHub?label=Docker%20Build)\n![Docker Pulls](https://img.shields.io/docker/pulls/wernerfred/docker-dyndns?label=Docker%20Pulls)\n![GitHub](https://img.shields.io/github/license/wernerfred/docker-dyndns?label=License)\n![Docker Image Size (latest semver)](https://img.shields.io/docker/image-size/wernerfred/docker-dyndns?label=Image%20Size)\n![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/wernerfred/docker-dyndns?label=Latest%20Release)\n![Docker Image Version (latest semver)](https://img.shields.io/docker/v/wernerfred/docker-dyndns?label=Latest%20Image)\n![GitHub Release Date](https://img.shields.io/github/release-date/wernerfred/docker-dyndns?label=Release%20Date)\n\n\n# Host your own Dyndns Server using Docker\n\nThis project uses ```bind9``` and ```go``` inside a ```docker``` container to build a dyndns server/service that can easily be self-hosted. We use ```bind``` as the DNS-Server whereas ```go``` is used to serve a API and update the DNS configuration. The API uses basic authentication to restrict the usage (see [Reverse Proxy](#reverse-proxy)). You need a server with a static IP, a domain and the possibility to add ```NS``` and ```A``` records to it's DNS configuration. Furthermore it is mandatory to define the subdomains which can be used to reduce abuse in case of a data breach.\n\n## Installation\n\n### Build from source\nTo build this project from source make sure to clone the repository from github and change your working directory into that newly created folder. Then simply issue the ```docker build``` command like shown:\n```\nroot@server /opt/docker-dyndns # docker build -t wernerfred/docker-dyndns .\n```\n\n### Pull from DockerHub\n\nAnother possibility is pulling the image from the [DockerHub repository](https://hub.docker.com/r/wernerfred/docker-dyndns). Builds of this image are automated and based on releases of the master branch.\n```\ndocker pull wernerfred/docker-dyndns\n```\n\n### Run Container\nTo run the container adjust the following command according to your needs:\n```\ndocker run -it -d \\\n           -p 53:53 \\ \n           -p 53:53/udp \\\n           -p 8080:8080 \\\n           -e BIND9_ROOTDOMAIN=dyndns.example.com \\\n           -e API_USER=user \\\n           -e API_PASSWORD=password \\\n           -e DYNDNS_TTL=60 \\\n           -e DYNDNS_DOMAINS='[\"sub1\", \"sub2\"]' \\\n           wernerfred/docker-dyndns\n```\nWith the variable ```BIND9_ROOTDOMAIN``` you set the domain of your dyndns server (See [DNS configuration](#dns-configuration)). With ```DYNDNS_DOMAINS``` you define the allowed dynamic subdomains in a json like array. Subdomains not listed there can not be updated later on. This keeps the consequences relatively small in case your API username and password gets exposed as only the defined subdomains can be updated. You can add a volume to the container to make the dns configuration persistant: ```-v /choose/path/on/host/:/var/cache/bind/```. This enables you to stop the container and add some more allowed subdomains to the environment variables without loosing the current dyndns configuration/information for the next start up.\n### Reverse proxy\nI highly recommend to use a reverse proxy on your system to kind of secure the API access. If you are using ```apache2``` you can orient yourself on the following configuration:\n```\n\u003cIfModule mod_ssl.c\u003e\n\u003cVirtualHost *:443\u003e\n\n    ProxyPreserveHost On\n    ProxyRequests off\n    ProxyPass / http://localhost:8080/\n    ProxyPassReverse / http://localhost:8080/\n\n    ServerName ddns.example.com\n\n    ServerAdmin webmaster@example.com\n\n    ErrorLog /your/path/to/logs/error.log\n    CustomLog /your/path/to/logs/access.log combined\n\nSSLCertificateFile /your/path/to/fullchain.pem\nSSLCertificateKeyFile /your/path/to/privkey.pem\n\n\u003c/VirtualHost\u003e\n\u003c/IfModule\u003e\n```\nMake sure to include a redirect to https (:443) into the http (:80) configuration file like that:\n```\nRewriteEngine on\nRewriteCond %{SERVER_NAME} =ddns.example.com\nRewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]\n```\n### DNS configuration\nTo allow your dyndns server to be reached and used you need to add some DNS records of your existing domain. Like in that whole README i assume you own the domain ```example.com```. If the dyndns domains should use ```dyndns.example.com``` as their root domain we need the following records:\n```\ndyndns      IN NS      ddns\nddns        IN A       \u003cIP of your docker host\u003e\n```\nThrough that we are telling the internet that the subdomain dyndns(.example.com) uses a different nameserver which can be reached under ddns(.example.com). Of course, the latter domain needs to be defined to be reached, therefore we need the second record. Keep in mind that if you want the nameserver to be a subdomain of the domain it is responsible for you will need a so called glue record on the parent zone to be able to reache the nameserver.\n\nIn case you do not like the dyndns address, you can simply add another ```CNAME``` record to beautify your dynamic address:\n```\nhome      IN CNAME     sub1.dyndns.example.com.\n````\n## Using the API\n\n### Browser\nIn modern browsers you can simply open the update URL:\n```\nhttps://ddns.example.com/update?domain=sub1\u0026ip=1.2.3.4\n```\nYou will then be promted for your API credentials that can be defined via the ```API_USER``` and ```API_PASSWORD``` variables:\n\n![alt text](https://github.com/wernerfred/docker-dyndns/blob/master/dyndns-browser.png \"Using the API via browser\")\n### CLI\nIt is also possible to use the API via command line tools like ```curl```. That command can then be used as a cronjob to constantly update the IP. The tool ```curl``` also provides the functionality to include basic authentication headers with the ```--user``` option:\n```\ncurl --user user:password https://ddns.example.com/update?domain=sub1\u0026ip=1.2.3.4\n```\nYou can obtain the current public IPv4 adress by using the ```dig``` command and save it into a variable for later usage (e.g. in a script):\n```\nIP=`dig @resolver1.opendns.com A myip.opendns.com -4 +short`\n````\n### Router\nAs modern routers provide a gui to configure custom dyndns services this project can also be used together with those. Usually the router uses basic authentication with the values of the user and password fields:\n\n![alt text](https://github.com/wernerfred/docker-dyndns/blob/master/dyndns-fritzbox.png \"Using the API via a router gui\")\n\nThe url then looks like this:\n```\nhttps://ddns.example.com/update?domain=\u003cdomain\u003e\u0026ip=\u003cipaddr\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwernerfred%2Fdocker-dyndns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwernerfred%2Fdocker-dyndns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwernerfred%2Fdocker-dyndns/lists"}