taegost/aws-ddns repository overview

⁠Summary

The AWS DDNS for Docker⁠ project is a container that performs a simple task: Whenever your external (WAN) IP address changes, update one or more DNS records in Amazon Route 53.

⁠Description

This project is aimed at anybody who self-hosts services without a static IP and uses Route 53 for their domain DNS. Whether you use it to connect to your home VPN, host game servers, or have a small home business, this is a quick, free, and easy alternative to services such as DynDNS.

By using this container you'll have your own self-hosted dynamic DNS updater up and running in a matter of minutes!

If you are hosting multiple domains (or sub-domains), you can enter them all, leaving a space between each
Example: shop.example.com mail.mycustomdomain.com vpn.familynamehere.com

⁠Pre-Requisites

• Get the Zone ID⁠ for the hosted domain from the Route 53 Hosted Zones console
• Create a new user
  • In the new user, go to Security Credentials -> Access Keys
  • Click Create Access Key
  • Choose Other and click 'Next'
  • Description Tag Value: Used by AWS-DDNS container to update DNS records
  • Make sure you record the Access Key ID and Access Key Secret
  • Click Done
• Edit the new user and click Inline Policies
• Use the Visual Editor:
  • Service: Amazon Route 53
  • Actions: Add ChangeResourceRecordSets and `
  • Effect: Allow
  • Resources: Under HostedZone, click Add ARN. In the ID field, enter the Zone ID you got earlier
    • Example: arn:aws:route53:::hostedzone/Z148QEXAMPLE8V
• Click Review Policy
• Give the policy a descriptive name
• Click Create Policy

Here is a JSON version ready to drop-in, all you have to do is change the Resource ARN

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "VisualEditor0",
			"Effect": "Allow",
			"Action": [
				"route53:ChangeResourceRecordSets",
				"route53:ListResourceRecordSets"
			],
			"Resource": "arn:aws:route53:::hostedzone/Z148QEXAMPLE8V"
		}
	]
}

⁠Environment Variables

All variable names and values are case-sensitive!

Any variable with a blank default is REQUIRED, the container will not start properly without them being defined.

⁠Docker Configuration

The container doesn't require any volumes or special setup besides the proper values in the environment variables. It MUST be able to connect to the internet.

⁠Using Docker Run

$ docker run -d \
    --name aws-ddns \
    -e AWS_ACCESS_KEY="AK6fakekey4EE" \
    -e AWS_SECRET="SuperDuperSecret" \
    -e AWS_ZONE_ID="Z0000fakezone000" \
    -e DOMAIN="example.com" \
    taegost/aws-ddns

If you're updating multiple domains, change the DOMAIN line to something like:

-e DOMAIN="shop.example.com mail.mycustomdomain.com vpn.familynamehere.com" \

⁠Using Docker Compose

The latest version of the sample docker-compose.yml will always be found in the root of the repo.

services: 
  aws-ddns: 
    image: taegost/aws-ddns:latest
    restart: unless-stopped
    environment:
      AWS_ACCESS_KEY: AK6fakekey4EE
      AWS_SECRET: SuperDuperSecret
      AWS_ZONE_ID: Z0000fakezone000
      DOMAIN: example.com
      DNS_TTL: 300
      RECHECK_SECS: 900

If you're updating multiple domains, put a space between each entry in the DOMAIN variable, like:

DOMAIN: shop.example.com mail.mycustomdomain.com vpn.familynamehere.com

⁠Image Tags

Images are published to Docker Hub at taegost/aws-ddns.

⁠Why No Date or "Weekly" Tag?

A weekly tag would be a moving pointer, semantically identical to latest. It would add noise to Docker Hub without adding meaning — anyone pinning to weekly gets the same behavior as pinning to latest. The tags above cover all real use cases:

• Staying current: use latest
• Stability: pin to a semver tag (1.2.3)
• Traceability: use the sha-<commit> tag to trace any image back to its exact source commit

The weekly scheduled pipeline rebuild ensures latest always incorporates the most recent base image security patches, even without a code change.