Repository Overview

Like all cool websites, arc42 has a status-subdomain, showing usage- and repo statistics for its domains and subdomains.

This is a multi-repo, and the directories are organized as follows:

Static Jekyll Site	Documentation	Statistic service (Go app)
/docs	/documentation	/go-app
Jekyll/Github-pages based static website.	arc42-based technical documentation, created with docToolchain.	Cloud-based statistics service written in Golang

Development and Build Targets

We use make (Makefile, see ADR-0020) as the single entry point for development, database schema management, testing, and deployment:

Local Development

This site runs as two processes during local development:

make backend    # terminal 1: run the Go statistics service on :8043
make site       # terminal 2: run the Jekyll dev server on :4046
make doctor     # verify setup health (Docker, Go, flyctl, Atlas, secrets, ports)
make help       # show all available make targets

make site (aliased as make dev) loads docs/_config.dev.yml, pointing the static site to the local backend. The deployed site uses _config.yml (pointing to Fly.io).

The Jekyll dev server serves on 4046, not Jekyll's default 4000, so it can run alongside the other arc42 sites' dev servers without a clash — see raw/port-assignment.md in meta.arc42.org for the full assignment. Jekyll binds 4046 inside the container as well as on the host, so its "Server address:" startup banner names the real port. Three places must stay in step: SITE_PORT in the Makefile, the mapping plus --port in docs/docker-compose.yml, and EXPOSE/CMD in docs/Dockerfile. The Go backend keeps 8043 — that is this repo's own second port, not part of the site assignment.

The backend requires go-app/set-api-keys.sh, created from template:

cp go-app/set-api-keys.sh.template go-app/set-api-keys.sh

Maintainer login (registrations page)

/registrations on the service is for people with push access to arc42/status.arc42.org-site only (ADR-0022). To use it locally:

1. Create a GitHub OAuth App (GitHub → Settings → Developer settings → OAuth Apps), homepage http://localhost:4046, authorization callback URL http://localhost:8043/auth/callback.
2. Put its client ID and a new client secret into go-app/set-api-keys.sh, together with SESSION_KEY (openssl rand -base64 32) and PUBLIC_BASE_URL=http://localhost:8043 (see set-api-keys.sh.template).
3. make backend, then open http://localhost:8043/registrations.

Production uses a second OAuth App with callback https://arc42-stats.fly.dev/auth/callback; its values are fly secrets (make fly-secrets lists them). Without the login variables /registrations answers 503. Locally the site's web fonts may not load on the page, because the Jekyll dev server sends no CORS headers for them. Set the fly secrets before merging to main, because that merge deploys the service.

Database & Schema Management (Atlas)

Database schemas for both local SQLite (~/arc42-stats-dev.db) and production TursoDB (libsql://...) are declaratively managed with Atlas (ADR-0013):

make db-apply-dev   # Apply schema.hcl to local development SQLite DB
make db-apply-prod  # Apply schema.hcl to production TursoDB
make db-diff-dev   # Dry-run / diff schema against local dev DB
make db-diff-prod  # Dry-run / diff schema against production TursoDB
make db-validate   # Validate schema syntax against an in-memory DB
make db-shell-dev  # Open interactive sqlite3 shell on local dev DB

Availability is measured by an external cron trigger (cron-job.org, every ~15 minutes, ADR-0019) calling the secure POST /api/probe endpoint on the Go backend service, which writes availability records into TursoDB. Locally: make db-apply-dev once, then make probe.

Fly.io Deployment & Diagnostics

The backend Go app is hosted on Fly.io (ADR-0008). Manage deployments directly via make:

make fly-deploy   # Deploy backend Go service to Fly.io
make fly-status   # Show status of Fly.io app and machines
make fly-logs     # Tail live production logs from Fly.io
make fly-ssh      # Open SSH console session on running Fly.io instance
make fly-secrets  # List secrets configured on Fly.io

Build, Test & Lint

make build    # Compile the Go service to go-app/arc42-status
make test     # Run Go unit tests
make lint     # Run golangci-lint over the Go code

Version history

The site carries a semantic version, shown in its footer beside the commit and date of the deploy that built it. It lives in version in docs/_config.yml and is raised by hand. The Go statistics service versions itself separately — that history is in go-app/main.go.

Version	What it marks
2.2.4	Current release.
2.x	Reworked user interface, and the backend rewritten.
1.5.x	The Go statistics service, running on fly.io.
1.0.0	The static site on its own — no backend at all, before fly.io.

Technologies used

Development and Feature Planning

Upcoming features and are planned with a GitHub project

Supported by INNOQ

This work is actively supported by INNOQ Deutschland GmbH.

Licence

This content is provided as-is, without any guarantees. It is open-source under the Creative-Commons-ShareAlike 4.0 licence:

• see the original text and the
• legal details

Created 2023 by Dr. Gernot Starke and contributors.