Sign inSign up

aeciopires/countdown

By aeciopires

•Updated 2 days ago

A web application developed in Golang for countdown time

Image
1

4.1K

aeciopires/countdown repository overview

⁠countdown

A lightweight, stateless countdown timer web app written in Go. The whole frontend (HTML, CSS and vanilla JS) is embedded in a single static binary, packaged in a scratch image that runs as a non-root user.

Source code: https://github.com/aeciopires/countdown⁠

countdown

⁠Table of Contents

⁠Quick start

docker pull aeciopires/countdown:latest
docker run -d -p 8080:8080 --rm --name countdown aeciopires/countdown:latest

Open http://localhost:8080⁠ in your browser.

Stop it with:

docker stop countdown

⁠Features

Countdown timer (web UI)

  • Set hours, minutes and seconds, then Start, Pause and Reset.
  • Accurate timing based on an absolute end time, so it does not drift when the browser tab is in the background.
  • Plays a beep and shows a "Finish!" message when the time is up.
  • Accessible display (role="timer", aria-live).

Production-ready container

  • Tiny scratch-based image containing only one static Go binary, with no shell or package manager.
  • Runs as an unprivileged user (65534, nobody) and works with a read-only root filesystem.
  • Multi-arch: linux/amd64, linux/arm64, linux/arm/v7 and linux/arm/v6 (runs on a Raspberry Pi).
  • Stateless: scale it horizontally with no shared storage.
  • Graceful shutdown: on SIGTERM/SIGINT it reports not-ready, waits SHUTDOWN_DELAY, then drains connections.

Built-in observability

  • Liveness (/health) and readiness (/ready) endpoints for Kubernetes probes.
  • Prometheus metrics in OpenMetrics format (/metrics), with trace exemplars on the latency histogram.
  • Structured JSON logs (one access-log line per request) with trace_id and span_id.
  • Optional OpenTelemetry distributed tracing over OTLP/HTTP.

All tags are multi-arch manifests for linux/amd64, linux/arm64, linux/arm/v7 and linux/arm/v6. Docker pulls the right variant for your machine automatically.

⁠Usage

⁠Change the port

The app listens on port 8080 by default. Use the PORT variable to change it:

docker run -d -p 3000:3000 -e PORT=3000 --rm --name countdown aeciopires/countdown:latest

Open http://localhost:3000⁠.

⁠Docker Compose
services:
  countdown:
    image: aeciopires/countdown:latest
    container_name: countdown
    ports:
      - "8080:8080"
    environment:
      LOG_FORMAT: json
      LOG_LEVEL: info
    read_only: true
    restart: unless-stopped
docker compose up -d
⁠Kubernetes (Helm)

A Helm 4 chart (Kubernetes 1.25+) is included in the source repository. It ships HPA, PDB, Ingress, ServiceMonitor and Grafana dashboards as optional features.

git clone https://github.com/aeciopires/countdown.git
cd countdown
helm upgrade --install countdown ./helm-chart -n countdown --create-namespace

See the chart documentation⁠ for all options.

⁠Environment variables

VariableDefaultDescription
PORT8080Listen port
LOG_FORMATjsonjson (one JSON object per line, with trace_id/span_id) or text
LOG_LEVELinfodebug, info, warn or error (probes and scrapes are logged at debug)
SHUTDOWN_DELAY5sHow long the app reports not-ready before closing the listener
OTEL_EXPORTER_OTLP_ENDPOINT(unset)Enables OpenTelemetry tracing over OTLP/HTTP (e.g. http://alloy:4318). All standard OTEL_* variables are honored.

⁠Endpoints

PathDescription
/The countdown web page
/healthLiveness probe: 200 OK while the process can serve HTTP
/readyReadiness probe: 200 READY, or 503 NOT READY while starting or shutting down
/metricsPrometheus metrics (OpenMetrics format)

Only GET and HEAD are accepted. Other methods get 405 Method Not Allowed.

⁠Observability

Metrics exposed at /metrics:

  • countdown_http_request_duration_seconds{method,route,code}: request latency histogram, with trace_id exemplars.
  • countdown_processed_ops_total: number of requests served by the static file handler (web page and assets).
  • countdown_build_info{version}: version of the running image.
  • Standard Go runtime and process metrics.

Example log line:

{"time":"2026-11-16T09:43:38.634Z","level":"INFO","msg":"http request","service":"countdown","method":"GET","path":"/","route":"/","status":200,"duration_ms":0.209,"remote_addr":"172.23.0.9:38144","user_agent":"curl/8.23.0","trace_id":"5ae5b1f1bca8833cdeb0a13059559dca","span_id":"9f54639e13654920"}

Enable tracing by pointing the app at an OTLP/HTTP collector:

docker run -d -p 8080:8080 --rm --name countdown \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://my-collector:4318 \
  aeciopires/countdown:latest

The source repository also includes a ready-to-run Docker Compose stack (Grafana, Prometheus, Loki, Tempo, Jaeger and Grafana Alloy) with three prebuilt dashboards (Overview, Logs and Traces), linking metrics, logs and traces with one click. See the observability stack docs⁠.

⁠Image details

ItemValue
Base imagescratch
Binary/countdown (static, CGO_ENABLED=0)
User65534:65534 (nobody)
Exposed port8080
Entrypoint["/countdown"]
Vulnerability scanEvery release is scanned with Trivy

Because the image has no shell, use the HTTP endpoints for health checks (for example, Kubernetes httpGet probes) rather than docker exec.

⁠Source code and contributing

Developed by Aécio dos Santos Pires: https://linktr.ee/aeciopires⁠

⁠License

GPL-3.0⁠

Tag summary

Content type

Image

Digest

sha256:813f51e86…

Size

6.2 MB

Last updated

2 days ago

docker pull aeciopires/countdown