Service naming migration plan¶

Review document for a piecewise, low-blast rename toward:

{scope}--{service}--{function}

No renames in this change set — only the plan. See also Architecture overview.

Invariant: Compose service key = container_name = Docker DNS name = target string. Never shorten (no nextcloud--app; always nextcloud--nextcloud--app).

Related risk: soda_scs_manager.settings, PHP defaults, .env host values, and scripts hardcode several Docker DNS names. Changing Compose without aliases or config cutover will break Manager, WissKI SPARQL, mounts, and pre-install scripts.

1. Goals and non-goals¶

Out of scope for early waves: public domains (drive.*, auth.*), OIDC client IDs based on URLs, Let's Encrypt cert names, Jupyter notebook prefix jupyter- (DockerSpawner), git/submodule folder names.

2. Naming model¶

Canonical definitions (scopes, service tokens, functions, delimiter rules): Service naming vocabulary.

Summary: {scope}--{service}--{function} — Compose env · software · role. Always explicit (nextcloud--nextcloud--app). Compose service key = container_name = DNS.

Compose service key and container_name must equal the target. During each wave, keep the Today value as a Docker network alias until cutover.

3. Complete Ist → Soll¶

During each wave: introduce Target as service key + container_name, keep Today as network alias until Env, scripts, Manager settings, and code fallbacks no longer reference Today.

3.1 Containers / Compose services¶

Platform rename count (excl. WissKI / notebooks): 28 targets + 1 optional dead (access-proxy) + 1 no-op (scs-manager--database). WissKI is a separate epic (Wave Z), not counted here.

3.2 Networks¶

3.3 Named volumes (optional)¶

Prefer keep external name: on the existing volume (no data copy). Logical Compose keys may follow the new scheme later.

3.4 Explicitly not renamed¶

4. Fallstrick-Klassen (immer alle prüfen)¶

Before each wave, search Today and planned Target; tick every class.

4.1 Environment (.env / example-env)¶

Central DNS knobs: SCS_CONTAINER_* (see Naming vocabulary — Environment variables). Scripts source 01_scripts/global/scs-container-names.bash.

4.2 Compose¶

• Service keys, container_name, depends_on, networks, volume keys
• extra_hosts, DJANGO_ALLOWED_HOSTS, JVM -Dhttp.proxyHost=scs--outproxy
• Traefik router/service label IDs (can lag; cosmetic/scripts)
• 00_custom_configs/** and already copied overrides in stack dirs (start.sh may skip overwrite)

4.3 soda_scs_manager config¶

Also update on-disk copies:

• scs-manager-stack/custom_configs/soda_scs_manager.settings.yml
• scs-manager-stack/volumes/drupal-root/custom_configs/…
• live config in MariaDB (export before / import or config:set on cutover)

Portainer / Jupyter / Nextcloud public baseUrls in settings usually stay on HTTPS domains — still verify nothing points at old Docker DNS.

4.4 Code hardcodes (soda_scs_manager + scripts)¶

Prefer env/settings; remaining defaults live in SodaScsDockerDns and scs-container-names.bash.

4.5 Ops / external¶

• Cron, systemd (scs-nextcloud-mounts.service — mostly paths, not DNS)
• Health dashboard container listing
• Portainer-deployed WissKI env (frozen TS_*)
• Operator muscle memory (docker compose logs scs--reverse-proxy)

5. Mandatory procedure per wave¶

1. Freeze + backup (DB + export soda_scs_manager.settings)
2. Ripgrep inventory for Today (and Target collisions)
3. Compose: add Target service + container_name; alias Today on shared network(s)
4. Recreate only affected containers
5. Smoke DNS: getent/curl Today AND Target from each consumer
6. Flip consumers: .env values, overrides, scripts → Target
7. Flip soda_scs_manager.settings + PHP defaults + custom YAML copies
8. Smoke Manager (DB provision, mounts, Portainer, SPARQL, WebProtégé API)
9. Soak; ripgrep Today == 0 in runtime paths; then remove alias
10. Docs + changelogs

Alias pattern¶

services:
  core--mariadb--db:
    container_name: core--mariadb--db
    networks:
      reverse-proxy:
        aliases:
          - scs--database   # Today — keep until cutover done

Verification¶

OLD='scs--database'
NEW='core--mariadb--db'
rg -n -g '!**/node_modules/**' -g '!**/.git/**' -g '!**/vendor/**' "$OLD" .

docker compose exec manager--drupal--app getent hosts "$OLD"   # after manager rename; use Today name during early waves
docker compose exec scs-manager--drupal getent hosts "$NEW"

scs-drush config:get soda_scs_manager.settings dbHost
scs-drush config:get soda_scs_manager.settings triplestore.generalSettings.internalHost
scs-drush config:get soda_scs_manager.settings webprotege.generalSettings.apiBaseUrl
scs-drush config:get soda_scs_manager.settings accessProxy.generalSettings.containerName
scs-drush config:get soda_scs_manager.settings --format=yaml | rg -n 'scs--|webprotege:|authproxy|mounter|nextcloud--'

6. Wave plan (piecewise)¶

Wave 0 — Prep¶

• [x] Env layer SCS_CONTAINER_* + scripts + SodaScsDockerDns (dev, 2026-09-08)
• [ ] Export soda_scs_manager.settings (prime)
• [x] Confirm: no COMPOSE_FILE path renames in container waves

Wave A — core--echo--app, health--health--app¶

• [x] Introduced with aliases scs--echo / scs--health (2026-09-08)
• [ ] Soak, then drop aliases

Low coupling; prove alias + recreate pattern.

Wave B — core--rclone--sidecar¶

• [x] Alias nextcloud-mounter (both nets)
• [ ] Flip NEXTCLOUD_MOUNTER_RC_URL / SCS_CONTAINER_NEXTCLOUD_MOUNTER after soak
• [x] Network: keep nextcloud-mounter-net name initially
• [x] Smoke: rc-API old+new DNS; scs:nextcloud-status reachable; reconcile mounted=5

Wave C — core--mariadb--db ⚠¶

• [x] Alias scs--database (long soak); compose key + container_name = core--mariadb--db; volume still scs--database-data (dev, 2026-09-08)
• [x] SCS_CONTAINER_DATABASE / scripts / start.sh use the new name (docker exec is not aliased)
• [ ] Flip remaining *_DB_HOST, JDBC, MYSQL_HOST, Drupal DB_HOST, dbHost, PHP fallbacks after soak
• [ ] Smoke Keycloak, Manager, Nextcloud, phpMyAdmin, project DB CRUD

Wave D — core--traefik--edge¶

• [x] Alias scs--reverse-proxy; compose key + container_name = core--traefik--edge (dev, 2026-09-08)
• [x] Docker network name: reverse-proxy unchanged; cert volume still scs--reverse-proxy-certificates
• [x] Traefik router label IDs still scs--reverse-proxy (intentional lag)
• [ ] Soak, then drop alias; optionally rename router labels later

Wave E — core--portainer--app, dbms--*¶

• [x] Aliases scs--portainer / scs--phpmyadmin / scs--forward-auth (dev, 2026-09-08)
• [x] Portainer volume still scs--portainer-data; Traefik router label IDs lag
• [x] Traefik dbms-sso still calls http://scs--forward-auth:4181 (alias; no Traefik recreate)
• [ ] Soak, then flip middleware URL + drop aliases

Wave F — opengdb--* ⚠ Manager + WissKI¶

• [x] Aliases scs--rdf4j / scs--authproxy / scs--outproxy / scs--opengdb-proxy (dev, 2026-09-08)
• [x] Submodule compose keys parked on profile opengdb-legacy-keys; new keys live in the override
• [x] INTERNAL_TS_BASE / Manager internalHost / WissKI TS_* still http://scs--authproxy:8000
• [x] DJANGO_ALLOWED_HOSTS includes both Today and Target
• [ ] Flip internalHost + WissKI TS_* + drop aliases after soak

Wave G — access-proxy¶

• [x] Confirmed dead: no Compose service, no running container (dev, 2026-09-08)
• [x] Removed SCS_CONTAINER_ACCESS_PROXY from env helper, example-env, Manager overrides
• [ ] Optional: delete leftover accessProxy.* from soda_scs_manager.settings if the module still stores it

Wave H — one Compose env per cycle¶

Suggested order:

1. [x] keycloak--keycloak--app (alias keycloak--keycloak; Traefik router labels lag; public KC_DOMAIN unchanged)
2. [x] manager--drupal--app / manager--redis--cache (aliases scs-manager--drupal / scs-manager--redis; Traefik router IDs lag; scs-drush host alias updated)
3. [x] nextcloud--* all five (aliases keep nginx upstreams, REDIS_HOST, OnlyOffice DocumentServerInternalUrl; Traefik router IDs lag; NEXTCLOUD_REDIS_HOST still nextcloud--redis)
4. [x] jupyterhub--jupyterhub--app / jupyterhub--spawner--builder (JUPYTERHUB_SERVICE_NAME = Target for hub_connect_ip; notebooks jupyter-{user} unchanged; Traefik router IDs lag)
5. [x] webprotege--webprotege--app / webprotege--mongodb--db (aliases keep apiBaseUrl + webprotege.mongodb.host=wpmongo; Traefik label IDs lag)
6. [ ] website--* if enabled — skipped on this host (stack not in live COMPOSE_FILE; prepare files later or leave until website is enabled)

Each: introduce+alias → flip env/scripts (docker exec / compose keys) → smoke → drop alias after soak.

Wave H3 — Nextcloud (dev, 2026-09-08)¶

• [x] Compose keys + container_name for all five; aliases keep Today DNS
• [x] SCS_CONTAINER_NEXTCLOUD / _REDIS / _EDGE / _ODS / _ODS_EDGE flipped
• [x] NEXTCLOUD_REDIS_HOST still nextcloud--redis; nginx upstream / OnlyOffice DocumentServerInternalUrl still Today names
• [x] Traefik router label IDs lag (nextcloud--nextcloud-reverse-proxy, nextcloud--onlyoffice-reverse-proxy)
• [x] Volumes keep name: (nextcloud-data, onlyoffice-data, onlyoffice-log)
• [ ] Drop aliases + flip REDIS_HOST / nginx.conf / occ OnlyOffice internals after soak

Wave H4 — JupyterHub (dev, 2026-09-08)¶

• [x] Compose keys + container_name: jupyterhub--jupyterhub--app, jupyterhub--spawner--builder
• [x] Alias jupyterhub--jupyterhub on reverse-proxy; builder is build-only (replicas: 0)
• [x] JUPYTERHUB_SERVICE_NAME + SCS_CONTAINER_JUPYTERHUB / _BUILDER flipped to Target
• [x] Traefik router label IDs lag (jupyterhub--jupyterhub)
• [x] Notebook containers jupyter-{user} unchanged
• [ ] Drop hub alias after soak

Wave H5 — WebProtégé (dev, 2026-09-08)¶

• [x] Compose keys + container_name: webprotege--webprotege--app, webprotege--mongodb--db
• [x] Aliases webprotege (app), wpmongo + webprotege-mongodb (mongo)
• [x] SCS_CONTAINER_WEBPROTEGE / _MONGODB flipped; Manager apiBaseUrl still http://webprotege:8080
• [x] webprotege.mongodb.host=wpmongo unchanged (alias)
• [x] Volumes keep name: (webprotege-data, mongodb-data); network name: webprotege
• [x] Traefik router/service label IDs lag (webprotege, webprotege-nocache, …)
• [ ] Flip apiBaseUrl + mongodb.host + drop aliases after soak

Wave Z — WissKI instances — TODO / deferred¶

Not part of the current platform rename. Leave running stacks as {SERVICE_NAME}--{drupal|varnish|redis} (e.g. wisski-mit-nextcloud-mount--drupal).

Why it is harder than Waves A–H:

1. External Compose, not root COMPOSE_FILE: wisski-base-stack docker-compose.yml (local checkout repos/wisski-base-stack). Container names are ${SERVICE_NAME}--drupal / --varnish / --redis; Varnish VARNISH_BACKEND_HOST=${SERVICE_NAME}--drupal.
2. Needs its own release of wisski-base-stack (and likely Manager Portainer template / env wiring) before any live cutover.
3. Many living stacks via Portainer — rename is rolling redeploy, not one docker compose up.
4. Scope token still open — early draft used proj-{id}--drupal--app. Prefer something closer to Today’s SERVICE_NAME, e.g. wisski--{id}--drupal--app / wisski--{id}--varnish--edge / wisski--{id}--redis--cache (three segments, function vocabulary). Exact {id} mapping (slug vs Drupal project id vs current SERVICE_NAME) is undecided.

Checklist when we pick this up:

• [ ] Decide scope/id scheme (wisski--{id}--* vs proj-{id}--* vs keep {SERVICE_NAME}--* + only add function)
• [ ] Patch wisski-base-stack compose (container_name, VARNISH_BACKEND_HOST, Traefik label IDs, volume name: policy)
• [ ] Tag/release wisski-base-stack; point Manager/Portainer at the new tag
• [ ] Migration path for existing stacks (alias soak vs recreate-only for new projects)
• [ ] Scripts (01_scripts/wisski/*), docs, architecture inventory
• [ ] Do not conflate with public Hosts (*.wisski.…) or Nextcloud Team Folder labels

Until then: platform migration is done for shared stacks; WissKI stays on Today names.

7. PR slicing¶

Never combine alias removal with unrelated features. Never mix container DNS renames with COMPOSE_FILE directory moves.

8. Rollback¶

1. Backup Compose + .env + settings export.
2. While alias exists: revert flip commits only.
3. After alias removed: restore alias first, then debug.
4. Manager: restore soda_scs_manager.settings.
5. WissKI: restore TS_* / SALZ or re-run tuning with old INTERNAL_TS_BASE.

9. Open decisions¶

1. Scope token for OpenGDB: opengdb (above) vs ts — prefer Compose-honest opengdb.
2. Health: health--health--app (explicit) vs shorter — keep explicit.
3. Docker network reverse-proxy: rename late / never?
4. Alias soak duration (staging / prime)?
5. Prime settings cutover: Drush update hook vs manual config:set?
6. ~~Is scs--access-proxy dead?~~ Yes — removed from compose/env (Wave G).
7. Confirm website keeps private MariaDB or moves to core--mariadb--db only.
8. WissKI / Wave Z (deferred): Prefer wisski--{id}--{drupal|varnish|redis}-style names over proj-{id}--*. Exact {id} (current SERVICE_NAME slug vs numeric project id) and whether the third segment is software (drupal) or function (app / edge / cache) — decide in the wisski-base-stack release, not in this deployment cycle.

See also¶

• Naming vocabulary
• Architecture overview
• Glossary
• Nextcloud mount sidecar
• WissKI stack — internalHost
• Pre-start steps — start.sh / DB bootstrap