title	Sunbeam Wiki Image
description	Custom MediaWiki image with nginx, OIDC auth, and the Beam skins.
tags	mediawiki wiki docker sunbeam

Sunbeam Wiki Image

Custom MediaWiki image used by the Sunbeam infrastructure. It is based on the upstream mediawiki:stable-fpm-alpine image and bundles everything needed to run as a Kubernetes workload behind Sunbeam Proxy.

Documentation

• Architecture — image anatomy and config wiring
• Skins — token model, stylesheet sync, TOC, appearance panel
• Extensions — enabled set, Postgres notes, OpenSearch
• Local Development — dev.sh, seed data, sync workflow
• Deployment & CI — container workflow, ghcr access, rollout

What's inside

• MediaWiki — upstream stable-fpm-alpine release.
• nginx — terminates HTTP inside the Pod and forwards dynamic requests to php-fpm via FastCGI.
• PluggableAuth + OpenIDConnect — OIDC login via Hydra (auth.DOMAIN_SUFFIX).
• Beam skins — custom Sunbeam Studios skins (skins/Beam light and skins/BeamDark dark), styled after the Beam design language (https://design.sunbeam.pt). BeamDark is the default theme; users can switch to Beam in their preferences.
• QoL extensions — VisualEditor, Echo, Cite, Popups, RevisionSlider, AdvancedSearch, CodeMirror and more (see Extensions).
• php-fpm status page — exposed on /status for php-fpm-exporter.

Build

Builds run in CI on every push to main and on v* tags (.github/workflows/container.yaml). For a manual build:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/sunbeamdotpt/wiki:latest \
  --push .

The short image name wiki is resolved to ghcr.io/sunbeamdotpt/wiki:latest in the production overlay (overlays/kustomization.yaml).

Run locally

For skin development there is a dev-mode setup that needs no image build: it runs the upstream MediaWiki (Apache) image with SQLite and bind-mounts skins/, so CSS/PHP edits are live on reload.

./dev.sh up     # first run installs MediaWiki, takes a few minutes
./dev.sh logs   # follow logs
./dev.sh down   # stop
./dev.sh reset  # wipe the dev database and start fresh

The dev wiki runs at http://localhost:8080 (login admin / devpassword) with BeamDark as the default skin and all caching disabled (config/dev-settings.php). Wikipedia-style infoboxes are enabled (Scribunto + TemplateStyles); run ./dev.sh seed to import the template set from dev/seed/ (see dev/seed/README.md). To exercise the full production image instead:

docker run --rm -it \
  -p 8080:80 \
  -e MEDIAWIKI_DB_HOST=postgres-rw.data.svc.cluster.local \
  -e MEDIAWIKI_DB_NAME=wiki_db \
  -e MEDIAWIKI_DB_USER=wiki \
  -e MEDIAWIKI_DB_PASSWORD=... \
  -e MEDIAWIKI_SERVER=https://wiki.artemis.cdg.DOMAIN_SUFFIX \
  ghcr.io/sunbeamdotpt/wiki:latest

Expected environment variables

Variable	Purpose
MEDIAWIKI_DB_HOST	Postgres host
MEDIAWIKI_DB_NAME	Postgres database name
MEDIAWIKI_DB_USER	Postgres user
MEDIAWIKI_DB_PASSWORD	Postgres password
MEDIAWIKI_OIDC_CLIENT_ID	Hydra / SSO gateway client ID
MEDIAWIKI_OIDC_CLIENT_SECRET	Hydra / SSO gateway client secret
MEDIAWIKI_SERVER	Canonical public URL
MEDIAWIKI_ADMIN_USER / MEDIAWIKI_ADMIN_PASSWORD	Used only by the first-time install Job

Entrypoint

entrypoint.sh starts php-fpm and nginx, then supervises both processes. If either process exits the container shuts down gracefully.

It also appends require_once "$IP/beam-settings.php"; to LocalSettings.php (idempotently) once that file exists. The shipped config/beam-settings.php loads both Beam skins and sets BeamDark as $wgDefaultSkin; because the require sits at the end of LocalSettings.php it overrides any earlier value. On a fresh install this takes effect from the first container start after the install Job has written LocalSettings.php.

Repository layout

File	Purpose
Dockerfile	Image build
entrypoint.sh	Container entrypoint
.github/workflows/container.yaml	Multi-arch build/push to ghcr
config/beam-settings.php	Loads the Beam skins, sets BeamDark as default, enables extensions
config/dev-settings.php	Dev-only settings (cache off, errors visible)
compose.dev.yml / dev.sh	Dev-mode wiki (upstream image + SQLite, live skins)
dev/seed/	Wikipedia infobox template exports + stubs
dev/sync-skins.py	Regenerates the BeamDark stylesheet from the Beam one
docs/	Documentation tree (served by the docs-server)
AGENTS.md	Contributor/agent conventions
skins/Beam/	Beam skin (light)
skins/BeamDark/	Beam skin (dark, default)
.dockerignore	Build context exclusions
README.md	This file