DDNS Docker

• Basic Features
  • Based on Alpine Linux, minimal compiled image size (< 7MB)
  • Multi-architecture support (amd64, arm64, arm/v7, arm/v6, ppc64le, s390x, 386, mips64le)
  • Built-in scheduler, automatic updates every 5 minutes by default
  • No external dependencies, ready to use, optimized performance with low resource usage
• Configuration Methods:
  • CLI Command Line Parameters
  • JSON Configuration File
  • Environment Variables

Image Information

Image Versions

DDNS image versions (Docker Tags):

• latest: Latest stable release (default stable release)
• next: Next beta version
• edge: Latest development build, unstable (master branch)

docker pull newfuture/ddns:latest
docker pull newfuture/ddns:next

You can also specify a specific version, for example:

docker pull newfuture/ddns:v4.0.0

Image Sources

Images are published to the following registries:

• Docker Hub: docker.io/newfuture/ddns
• GitHub Packages: ghcr.io/newfuture/ddns

Supports docker pull ghcr.io/newfuture/ddns

Running with docker run

DDNS Docker image supports three configuration methods: command line, environment variables, and config file.

• When command line arguments are set, the container will run DDNS directly once without enabling the scheduler.
• If you need scheduled updates, please use environment variables or config file methods.

Notes (for docker run):

• If using -v to mount config files or directories, ensure the /ddns/ directory in the container contains valid config files (like config.json), otherwise DDNS will not work properly.
• If using --network host, ensure your Docker daemon is properly configured to support this mode.
• Use -d parameter to run the container in the background. Make sure you understand basic Docker operations before using.
• Use -e DDNS_XXX=YYY parameters to set environment variables, and the DDNS program in the container will automatically read these variables.

Using Command Line Parameters (CLI)

You can refer to the CLI parameter documentation for a detailed parameter list. In this case, docker run -v /local/config/:/ddns/ --name=ddns --network=host newfuture/ddns is equivalent to the ddns command line and will not execute scheduled tasks.

This method is suitable for one-time runs or debugging scenarios. Parameters are identical to DDNS command line parameters.

# View ddns command line parameters, equivalent to ddns -h
docker run --rm newfuture/ddns -h
# Add ddns --debug parameter to enable debug mode (or --log.level=debug)
docker run --rm --network=host newfuture/ddns --debug --dns=dnspod --id=12345 --token=mytokenkey --ipv4=www.example.com --ipv4=ipv4.example.com --index4 public
# Debug inside container
docker run -it newfuture/ddns sh

Using Configuration File (JSON)

The working directory inside the Docker container is /ddns/, and the default config file is mapped to /ddns/config.json inside the container.

docker run -d -v /host/config/:/ddns/ newfuture/ddns

Where /host/config/ is your local directory containing config.json. For details on config.json content, refer to JSON Configuration File Documentation.

Using Environment Variables (ENV)

Environment variables are similar to command line parameters, with a DDNS prefix, recommended in uppercase. Array types need to use JSON format or be wrapped in single quotes.

You can also use the --env-file parameter to load environment variable files.

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4='["example.com","www.example.com"]' \
  -e DDNS_INDEX4='["public",0]' \
  --network host \
  --name ddns \
  newfuture/ddns

To learn about all supported environment variables, please refer to Environment Variable Configuration Documentation.

Network Modes

Host Network Mode

Using --network host allows the container to directly use the host's network, so DDNS can correctly obtain the host's IP address.

For Public or URL modes, host network is usually not required.

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

Bridge Network Mode (Default)

If you don't want to use host network mode, you can also use the default bridge mode, but note that the container will have its own IP. You need to use public mode to get the public IP:

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  -e DDNS_INDEX4=public \
  newfuture/ddns

Advanced Configuration

Custom Cron Schedule

By default, the DDNS container automatically updates DNS records every 5 minutes. You can customize the scheduled task execution interval using the DDNS_CRON environment variable.

The DDNS_CRON environment variable uses standard cron expression format: minute hour day month weekday

Examples:

# Run every 10 minutes
docker run -d \
  -e DDNS_CRON="*/10 * * * *" \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

# Run every hour
docker run -d \
  -e DDNS_CRON="0 * * * *" \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

# Run once daily at 2 AM
docker run -d \
  -e DDNS_CRON="0 2 * * *" \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

# Run every minute (most frequent for cron)
docker run -d \
  -e DDNS_CRON="* * * * *" \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4=example.com \
  --network host \
  newfuture/ddns

Cron Expression Reference:

Field	Allowed Values	Allowed Special Characters
Minute	0-59	* , - /
Hour	0-23	* , - /
Day	1-31	* , - /
Month	1-12	* , - /
Weekday	0-7	* , - /

Common Expression Examples:

• */5 * * * * - Every 5 minutes (default)
• */10 * * * * - Every 10 minutes
• */15 * * * * - Every 15 minutes
• 0 * * * * - Every hour
• 0 */2 * * * - Every 2 hours
• 0 0 * * * - Daily at midnight
• 0 2 * * * - Daily at 2 AM
• 0 0 * * 0 - Weekly on Sunday at midnight

Docker Compose Example:

version: "3"
services:
    ddns:
        image: newfuture/ddns:latest
        restart: always
        network_mode: host
        environment:
            - DDNS_CRON=*/10 * * * *  # Run every 10 minutes
            - DDNS_DNS=dnspod
            - DDNS_ID=12345
            - DDNS_TOKEN=mytokenkey
            - DDNS_IPV4=example.com

Multi-Domain Configuration

Environment variable method for configuring multiple domains:

docker run -d \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV4='["example.com", "www.example.com", "sub.example.com"]' \
  --network host \
  newfuture/ddns

Command line parameter method for configuring multiple domains:

docker run --rm --network host newfuture/ddns \
  --dns dnspod \
  --id 12345 \
  --token mytokenkey \
  --ipv4 ipv4.example.com \
  --ipv4 www.example.com

Enable IPv6 Support

To use IPv6 in Docker containers, you need to ensure the Docker daemon is configured with IPv6 support:

1. Edit /etc/docker/daemon.json:

{
    "ipv6": true,
    "fixed-cidr-v6": "fd00::/80"
}

2. Restart Docker service:

sudo systemctl restart docker

3. Enable IPv6 when starting the container:

docker run -d \
  --network host \
  -e DDNS_DNS=dnspod \
  -e DDNS_ID=12345 \
  -e DDNS_TOKEN=mytokenkey \
  -e DDNS_IPV6=example.com \
  newfuture/ddns

Docker Compose Examples

Create a docker-compose.yml file:

Basic Environment Variable Configuration

version: "3"
services:
    ddns:
        image: newfuture/ddns:latest
        restart: always
        network_mode: host
        environment:
            - DDNS_DNS=dnspod
            - DDNS_ID=12345
            - DDNS_TOKEN=mytokenkey
            - DDNS_IPV4=example.com,www.example.com
            - DDNS_INDEX4=['public','url:https://api.ipify.org']
            - DDNS_LOG_LEVEL=WARNING

Using Configuration File

version: "3"
services:
    ddns:
        image: newfuture/ddns:latest
        restart: always
        network_mode: host
        volumes:
            - ./config:/ddns

Run Docker Compose:

docker-compose up -d

Using Custom Images

If you need to add other tools or customize the environment in the container, you can create your own Dockerfile based on the official image:

FROM newfuture/ddns:latest

# Install additional tools
RUN apk add --no-cache curl

# Add custom scripts
COPY custom-script.sh /bin/
RUN chmod +x /bin/custom-script.sh

# Override default entrypoint (optional)
# ENTRYPOINT ["/bin/custom-script.sh"]

Troubleshooting & FAQ

Container Can't Get Correct IP Address

Problem: DDNS cannot correctly obtain host IP

Solution:

1. Use --network host network mode
2. Or set -e DDNS_INDEX4=public to force using public API to get IP

No Scheduled Updates Received

Problem: Container runs but doesn't automatically update DNS

Solution:

1. Check container logs docker logs ddns
2. Confirm container is not paused docker ps -a
3. Try manual update execution docker exec ddns /bin/ddns

Exits Immediately After First Run

Problem: Container exits immediately after startup

Solution:

1. Add -it parameter to run interactively and see the issue docker run -it --rm newfuture/ddns
2. Check if environment variables or config files are set correctly

Network Connection Issues

Problem: Container cannot connect to DNS provider API

Solution:

1. Check network connectivity docker exec ddns ping api.dnspod.cn
2. Configure HTTP proxy -e DDNS_PROXY=http://proxy:port

More Resources

• DDNS GitHub Repository
• Docker Hub - newfuture/ddns
• Environment Variable Configuration Details
• JSON Configuration File Details
• Command Line Parameter Details

Configuration Examples for Different DNS Providers

CloudFlare

docker run -d \
  -e DDNS_DNS=cloudflare \
  -e DDNS_ID=user@example.com \
  -e DDNS_TOKEN=your_cloudflare_api_token \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-cloudflare \
  newfuture/ddns

Alibaba Cloud DNS

docker run -d \
  -e DDNS_DNS=alidns \
  -e DDNS_ID=your_access_key_id \
  -e DDNS_TOKEN=your_access_key_secret \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-alidns \
  newfuture/ddns

Huawei Cloud DNS

docker run -d \
  -e DDNS_DNS=huaweidns \
  -e DDNS_ID=your_access_key \
  -e DDNS_TOKEN=your_secret_key \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-huawei \
  newfuture/ddns

Tencent Cloud DNS

docker run -d \
  -e DDNS_DNS=tencentcloud \
  -e DDNS_ID=your_secret_id \
  -e DDNS_TOKEN=your_secret_key \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-tencent \
  newfuture/ddns

Custom Callback

# GET method callback
docker run -d \
  -e DDNS_DNS=callback \
  -e DDNS_ID="https://api.example.com/ddns?domain=__DOMAIN__&ip=__IP__" \
  -e DDNS_TOKEN="" \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-callback-get \
  newfuture/ddns

# POST method callback
docker run -d \
  -e DDNS_DNS=callback \
  -e DDNS_ID="https://api.example.com/ddns" \
  -e DDNS_TOKEN='{"api_key": "your_key", "domain": "__DOMAIN__", "ip": "__IP__"}' \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-callback-post \
  newfuture/ddns

Using Custom API Endpoints

docker run -d \
  -e DDNS_DNS=cloudflare \
  -e DDNS_ENDPOINT=https://api.private-cloudflare.com \
  -e DDNS_ID=user@example.com \
  -e DDNS_TOKEN=your_token \
  -e DDNS_IPV4='["example.com"]' \
  --name ddns-custom-endpoint \
  newfuture/ddns