feat(docker): add DDNS_CRON environment variable for customizable cron schedule

[Copilot]

Summary

Adds support for the DDNS_CRON environment variable to allow users to customize the scheduled task execution interval in Docker containers.

Problem

Users reported that manually modifying /etc/crontabs/root inside Docker containers to change the update frequency doesn't persist after container restarts. The hardcoded 5-minute schedule in entrypoint.sh was overwriting their changes on every restart, making it impossible to customize the update interval without rebuilding the image.

Reference: Issue #204 and related user requests

Solution

Implemented the DDNS_CRON environment variable that allows users to specify a custom cron schedule when running the Docker container. The schedule persists across container restarts and requires no modifications to container internals.

Implementation Details

• Modified docker/entrypoint.sh to read DDNS_CRON environment variable
• Uses shell parameter expansion: ${DDNS_CRON:-*/5 * * * *} for backward compatibility
• Updated user-facing message to display the active schedule
• Defaults to */5 * * * * (every 5 minutes) when not set

Usage Examples

Basic Usage

# Default behavior (every 5 minutes) - no change needed for existing users
docker run -d newfuture/ddns

# 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

# Every hour
docker run -d -e DDNS_CRON="0 * * * *" newfuture/ddns

# Daily at 2 AM
docker run -d -e DDNS_CRON="0 2 * * *" newfuture/ddns

Docker Compose

version: "3"
services:
  ddns:
    image: newfuture/ddns:latest
    restart: always
    network_mode: host
    environment:
      - DDNS_CRON=*/15 * * * *  # Every 15 minutes
      - DDNS_DNS=cloudflare
      - DDNS_ID=user@example.com
      - DDNS_TOKEN=my-api-token
      - DDNS_IPV4=example.com

Cron Expression Format

The DDNS_CRON variable accepts standard cron expressions in the format: minute hour day month weekday

Common 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

Documentation

Added comprehensive documentation in both Chinese and English:

• Docker documentation with examples and cron expression reference
• Environment variable documentation with detailed usage guide
• Included in environment variable reference tables

Backward Compatibility

✅ Fully backward compatible - existing containers continue to work without any changes

• If DDNS_CRON is not set, defaults to */5 * * * * (original behavior)
• Empty DDNS_CRON also defaults to the original 5-minute schedule
• No breaking changes to existing deployments

Testing

• ✅ All 831 existing unit tests pass
• ✅ Shell script syntax validation passes
• ✅ Manual testing confirms correct behavior for various schedules
• ✅ Tested default behavior, custom schedules, and edge cases

Files Changed

• docker/entrypoint.sh - Core implementation (3 lines modified)
• doc/docker.md - Chinese Docker documentation (89 lines added)
• doc/docker.en.md - English Docker documentation (88 lines added)
• doc/config/env.md - Chinese environment variable documentation (51 lines added)
• doc/config/env.en.md - English environment variable documentation (51 lines added)

Total: 5 files changed, 283 insertions(+), 2 deletions(-)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>能否将docker下的定时任务的周期做成环境变量的配置项？</issue_title>
<issue_description>按 #204 中的要求，修改 Docker 容器中的 /etc/crontabs/root 文件，但是容器重启之后内容又恢复了，能否将这个做成环境变量的配置项？</issue_description>

<agent_instructions>实现一个新的feature，修改docker 的entrypoint.sh,允许通过环境变量作为定时周期，参数替代默认的5分钟定时。</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes #573

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull Request Overview

This PR introduces the DDNS_CRON environment variable to allow users to customize the cron schedule for DNS update tasks in Docker containers. Previously, users had to modify /etc/crontabs/root inside containers, but these changes were lost on restart due to the hardcoded 5-minute schedule in the entrypoint script.

Key Changes:

• Implemented DDNS_CRON environment variable with backward-compatible default of */5 * * * *
• Modified Docker entrypoint to use the customizable schedule while maintaining existing behavior when not set
• Added comprehensive documentation in both Chinese and English with examples and cron expression references

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docker/entrypoint.sh	Core implementation using shell parameter expansion to read DDNS_CRON with fallback to default 5-minute schedule
doc/docker.md	Chinese documentation with usage examples, cron expression reference, and Docker Compose configuration
doc/docker.en.md	English documentation with usage examples, cron expression reference, and Docker Compose configuration
doc/config/env.md	Chinese environment variable reference documentation including DDNS_CRON parameter details
doc/config/env.en.md	English environment variable reference documentation including DDNS_CRON parameter details