timerd

time management system with NTP synchronization and timezone support.

quick start

1. copy and edit .env:

cp .env.example .env
# edit NTP_SERVER, CHECK_TIMEZONES, intervals

2. run:

docker compose up

services

• timercat - server that provides time in various formats

  • GET /time - plain text date/time (default: UTC)
  • GET /time/json - json response with timestamp, formatted time, timezone, and ISO8601
  • GET /time/unix - unix timestamp
  • GET /time/iso - ISO8601 format
  • query parameter: ?tz=America/New_York for specific timezone (defaults to UTC if not specified)

• watchdog - NTP synchronization daemon

  • syncs time from configured NTP server using beevik/ntp library
  • provides gRPC time service for other components
  • tracks time drift and RTT (Round Trip Time)
  • defaults to UTC timezone for security (prevents host timezone disclosure)

• posters - Timezone checker daemon

  • periodically checks time for all configured regions
  • logs current time for each timezone

examples

# current time in UTC (default)
curl http://localhost:8080/time

# time in json format (UTC)
curl http://localhost:8080/time/json

# time for specific timezone
curl http://localhost:8080/time?tz=Asia/Tokyo
curl "http://localhost:8080/time?tz=America/New_York"

# unix timestamp
curl http://localhost:8080/time/unix

# ISO8601 format
curl http://localhost:8080/time/iso

configuration

see .env.example for all available options:

• NTP_SERVER - ntp server to sync from (default: time.google.com)
• SYNC_INTERVAL - how often to sync with NTP in seconds
• USE_ALL_TIMEZONES - enable checking all available timezones from IANA database (true/false)
• CHECK_TIMEZONES - list of timezones for posters to check (only used when USE_ALL_TIMEZONES=false)
• CHECK_INTERVAL - how often posters checks timezones in seconds
• TIMERCAT_PORT - http port for timercat (default: 8080)

development

protobuf code:

./gen.sh

locally without Docker:

cd cmd/watchdog && go run .
cd cmd/timercat && go run .
cd cmd/posters && go run .