Sign inSign up

aeciopires/my-world-cup-app

By aeciopires

•Updated 2 days ago

My World Cup web application

Image
1

653

aeciopires/my-world-cup-app repository overview

⁠My World Cup App

A lightweight web application that shows the FIFA World Cup 2026 (Canada / Mexico / USA) group standings, match results, knockout bracket and statistics, plus curated links to official FIFA resources.

Single static Go binary on a distroless, non-root image. No database, no required configuration: start the container and open your browser.

⁠Table of Contents

⁠Features

  • Group standings: computed from match results (played, won, drawn, lost, goals, goal difference, points).
  • Knockout stage: a graphical bracket from the Round of 32 to the Final, plus the match for third place, with the winner highlighted. Extra time and penalty shoot-outs are handled correctly. Round-by-round tables show the date, venue and result of each match.
  • Match list: every fixture with date, round, group, venue and result. You can filter by round, group and/or team, and combine the filters.
  • Statistics: top scorers (own goals excluded) and overall team records across the group and knockout stages.
  • Live data: data is fetched from openfootball/worldcup.json⁠ at startup and again whenever you click Update data. An embedded snapshot keeps the app working even without internet access.
  • Official FIFA links: team names, stadiums and host cities link to their fifa.com pages. A links page covers standings, fixtures, the match ball, posters, mascots, the official FIFA Sound playlist and more.
  • Dark / light theme: a toggle that the browser remembers.
  • Responsive layout: on phones, tables are restacked into compact cards.
  • Production-ready observability:
    • /healthz (liveness) and /readyz (readiness) probes, with graceful draining on shutdown
    • structured JSON logs that include trace IDs
    • Prometheus metrics at /metrics (OpenMetrics, with trace exemplars)
    • opt-in OpenTelemetry tracing via the standard OTEL_* variables

⁠Screenshots

Home (dark)Home (light)
Home page - dark themeHome page - light theme
Group Standings (dark)Knockout Stage (light)
Group standings - dark themeKnockout stage - light theme

⁠Quick Start

Pull the latest image:

docker pull aeciopires/my-world-cup-app:latest

Run it:

docker run --rm -p 8080:8080 aeciopires/my-world-cup-app:latest

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

⁠Usage

⁠Run in the background
docker run -d \
  --name my-world-cup-app \
  --restart unless-stopped \
  -p 8080:8080 \
  aeciopires/my-world-cup-app:latest

docker logs -f my-world-cup-app   # follow the logs
docker stop my-world-cup-app      # stop it
⁠Use a different port

Map any host port to the container's port 8080:

docker run -d -p 3000:8080 aeciopires/my-world-cup-app:latest
# http://localhost:3000

You can also change the port the app listens on inside the container:

docker run -d -e PORT=9090 -p 9090:9090 aeciopires/my-world-cup-app:latest
⁠Docker Compose
services:
  app:
    image: aeciopires/my-world-cup-app:latest
    container_name: my-world-cup-app
    ports:
      - "8080:8080"
    environment:
      LOG_FORMAT: json
    restart: unless-stopped
docker compose up -d

The image already declares a HEALTHCHECK, so docker ps reports the container as healthy without extra configuration.

⁠Kubernetes (Helm)

The source repository includes a Helm 4 chart, with probes, a non-root security context and Prometheus scrape annotations already set up:

git clone https://github.com/aeciopires/my-world-cup-app.git
cd my-world-cup-app
helm upgrade --install my-world-cup-app helm/my-world-cup-app \
  --namespace my-world-cup-app --create-namespace \
  --set image.repository=aeciopires/my-world-cup-app \
  --set image.tag=latest

⁠Configuration

All settings are environment variables. None of them are required, because each has a working default.

VariableDefaultDescription
PORT8080HTTP listen port
FETCH_TIMEOUT10sMaximum duration of one data refresh (Go duration, e.g. 15s, 1m)
LOG_FORMATjsonjson for log collectors, or text for a human-friendly format
SHUTDOWN_DRAIN_DELAY0sAfter SIGTERM, how long to keep serving while /readyz returns 503
OTEL_EXPORTER_OTLP_ENDPOINTunsetOTLP/HTTP collector URL (e.g. http://otel-collector:4318). Setting it turns tracing on
OTEL_SERVICE_NAMEmy-world-cup-appTrace service.name. The other standard OpenTelemetry SDK variables also apply
WORLDCUP_MATCHES_URLopenfootball 2026/worldcup.jsonMatch data source
WORLDCUP_GROUPS_URLopenfootball 2026/worldcup.groups.jsonGroup assignments source
WORLDCUP_TEAMS_URLopenfootball 2026/worldcup.teams.jsonTeam metadata source
WORLDCUP_STADIUMS_URLopenfootball 2026/worldcup.stadiums.jsonStadium data source

Example with tracing enabled and human-readable logs:

docker run -d -p 8080:8080 \
  -e LOG_FORMAT=text \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
  aeciopires/my-world-cup-app:latest

⁠Endpoints

MethodPathDescription
GET/Home: overview of results and upcoming matches
GET/groupsGroup standings and each group's matches
GET/knockoutKnockout bracket and round-by-round results
GET/matchesEvery fixture; optional ?round=, ?group=, ?team= filters
GET/statsTop scorers and team records
GET/linksOfficial FIFA resources
POST/refreshRe-fetch tournament data (returns 429 if a refresh is already running)
GET/healthzLiveness probe
GET/readyzReadiness probe
GET/metricsPrometheus / OpenMetrics metrics

⁠Image Details

  • Base image: gcr.io/distroless/static-debian13:nonroot, with no shell and no package manager, for a minimal attack surface.
  • User: runs as non-root UID/GID 65532.
  • Binary: static Go binary (CGO_ENABLED=0, stripped), built with Go 1.27.
  • Exposed port: 8080.
  • Healthcheck: built in (/app/server -healthcheck, which runs a local GET /healthz).
  • Entrypoint: /app/server.
  • Labels: standard OCI labels (org.opencontainers.image.version, .source, .licenses).

⁠Tags

TagDescription
latestMost recent published release
X.Y.Z (e.g. 1.4.0)A specific, immutable release. Recommended for production

Each tag is a multi-arch manifest. Docker pulls the right variant (amd64 or arm64) for your host automatically.

⁠Contributing and Support

Tournament data comes from the openfootball⁠ project. This is an unofficial fan project and is not affiliated with FIFA.

⁠License

Distributed under the GPL-3.0⁠ license.

Tag summary

Content type

Image

Digest

sha256:28932afc9…

Size

7.1 MB

Last updated

2 days ago

docker pull aeciopires/my-world-cup-app:1.4.0