Time Service

A deliberately small HTTP service that returns the current UTC time as JSON.

API

GET /

Example response:

{
  "timezone": "Etc/UTC",
  "datetime": "2026-07-24T20:15:23.123+00:00",
  "unixtime": 1784924123
}

GET /health

{
  "status": "ok"
}

Why the returned time is always UTC

The application does not use the container's local timezone.

It explicitly requests an aware UTC timestamp:

now = datetime.now(timezone.utc)

Both datetime and unixtime are then derived from that same value.

Docker containers use the host kernel's system clock, so the host server should have normal clock synchronisation enabled (for example systemd-timesyncd, chrony, or another NTP client). The host's configured timezone does not affect the API response.

Run locally

Build:

docker build -t time-service .

Run:

docker run --rm -p 8362:8362 time-service

Test:

curl http://localhost:8362/
curl http://localhost:8362/health

Run from the private registry

docker pull registry.stetho.me/time-service:latest
docker run -d \
  --name time-service \
  --restart unless-stopped \
  -p 8362:8362 \
  registry.stetho.me/time-service:latest

For a host where only nginx needs to reach the service, binding the published port to loopback is preferable:

docker run -d \
  --name time-service \
  --restart unless-stopped \
  -p 127.0.0.1:8362:8362 \
  registry.stetho.me/time-service:latest

GitHub Actions

Every push to main:

1. runs the tests;
2. builds the Docker image;
3. logs into registry.stetho.me;
4. pushes these tags:

registry.stetho.me/time-service:latest
registry.stetho.me/time-service:<full-git-commit-sha>

The workflow can also be run manually from GitHub Actions.

Required GitHub secrets

In the repository, create:

REGISTRY_USERNAME
REGISTRY_PASSWORD

Use credentials that have permission to push registry.stetho.me/time-service.

nginx

A minimal reverse-proxy location is:

server {
    server_name time.stetho.online;

    location / {
        proxy_pass http://127.0.0.1:8362;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

TLS configuration is intentionally omitted because it depends on how the host already manages certificates.

Development

Create a virtual environment and install the development dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

Run:

uvicorn app.main:app --reload --port 8362

Test:

pytest