Architecture overview (C4-style)¶

C4-inspired view of the SODa SCS Manager deployment: Compose app → Docker services → software modules → integration flows → configs and operational scripts.

Target container DNS (migration): {scope}--{service}--{function} — see Naming vocabulary. Ist→Soll and cutover: Naming migration plan.

Related detail pages: Service infrastructure, Naming vocabulary, Naming migration plan, Nextcloud mount sidecar, WissKI stack, Maintenance.

1. System context (C4 L1)¶

Who uses the platform and which external systems it talks to.

flowchart TB
  User[Platform user<br/>researcher / curator]
  Admin[Operator<br/>DevOps / SCS admin]

  subgraph SCS["SODa SCS Deployment"]
    Platform[SCS Platform<br/>Compose multi-stack:<br/>Manager · Drive · Code · Auth · Ontologies · Triplestore · Health]
  end

  IdP[Upstream IdP / DIDMOS<br/>optional federation]
  LE[Let's Encrypt]
  Reg[Container registries<br/>ghcr.io / Docker Hub]

  User -->|HTTPS apps| Platform
  Admin -->|Ops · Portainer · Health · backups| Platform
  Platform -.->|OIDC broker optional| IdP
  Platform -->|ACME / TLS| LE
  Platform -->|pull images| Reg

2. Containers — Compose app → Docker services (C4 L2)¶

Level: one Docker Compose project (root COMPOSE_FILE) plus per-project WissKI stacks created at runtime via Portainer.

flowchart TB
  User[User / Browser]

  subgraph Edge["Edge & shared infra"]
    Traefik[scs--reverse-proxy<br/>Traefik TLS + routing]
    DB[(scs--database<br/>MariaDB 11.5)]
    Portainer[scs--portainer]
    PMA[scs--phpmyadmin]
    FwdAuth[scs--forward-auth]
    Mounter[nextcloud-mounter<br/>rclone FUSE]
    Health[scs--health]
  end

  subgraph Apps["Application stacks"]
    KC[keycloak--keycloak]
    Mgr[scs-manager--drupal]
    MgrRedis[scs-manager--redis]
    NC[nextcloud--nextcloud--app]
    NCRP[nextcloud--nginx--edge]
    OO[nextcloud--ods--app]
    NCRedis[nextcloud--redis--cache]
    JH[jupyterhub--jupyterhub--app]
    WP[webprotege--webprotege--app]
    WPMongo[(webprotege--mongodb--db)]
    OpenGDB[OpenGDB<br/>nginx · AuthProxy · RDF4J]
  end

  subgraph WissKI["Per-project via Portainer"]
    WVarnish["{svc}--varnish"]
    WDrupal["{svc}--drupal"]
    WRedis["{svc}--redis"]
  end

  User --> Traefik
  Traefik --> KC
  Traefik --> Mgr
  Traefik --> NCRP
  Traefik --> JH
  Traefik --> WP
  Traefik --> OpenGDB
  Traefik --> Portainer
  Traefik --> PMA
  Traefik --> Health
  Traefik --> WVarnish

  KC --> DB
  Mgr --> DB
  NC --> DB
  WDrupal --> DB

  Mgr -.->|OIDC| KC
  NC -.->|OIDC| KC
  JH -.->|OIDC| KC
  WP -.->|OIDC| KC
  FwdAuth -.->|OIDC| KC
  PMA --> FwdAuth

  NCRP --> NC
  NCRP --> OO
  Mgr --> MgrRedis
  NC --> NCRedis
  WP --> WPMongo
  WVarnish --> WDrupal
  WDrupal --> WRedis

  Mgr -->|rc API| Mounter
  Mounter -->|WebDAV| NC
  JH -.->|rslave project folders| Mounter
  WDrupal -.->|rslave project folder| Mounter
  Mgr -->|deploy stacks| Portainer
  Portainer --> WissKI
  WDrupal -->|SPARQL| OpenGDB

Compose wiring (how the “App” is assembled)¶

Never pass -f manually for normal ops — see project stack-operations rules.

3. Components (software modules & extensions)¶

flowchart TB
  subgraph Manager["scs-manager--drupal"]
    SM[soda_scs_manager]
    OIDC_D[openid_connect]
    Theme[soda_scs_manager_theme]
    SM --> PortAPI[Portainer API]
    SM --> MountAPI[NextcloudMountManager]
    SM --> WPAPI[WebProtégé REST]
    SM --> KCAPI[Keycloak Admin]
    SM --> NCAPI[Nextcloud OCS/WebDAV]
  end

  subgraph NextcloudApps["nextcloud--nextcloud--app apps"]
    UOIDC[user_oidc]
    Social[sociallogin]
    OOApp[onlyoffice]
    Draw[drawio]
    TF[Group / Team Folders]
  end

  subgraph Jupyter["jupyterhub--jupyterhub--app"]
    GA[GenericOAuthenticator]
    Spawner[Spawner + group_map]
    Tools[spawner_image: wisski_py, OpenRefine, …]
  end

  subgraph KeycloakComp["keycloak--keycloak"]
    Realm[Realm from scs-realm.json.tpl]
    Clients[OIDC clients: Manager, Drive, Code, DBMS, WebProtégé, DIDMOS, Health]
    ThemeKC[SCS theme]
  end

  subgraph WissKIComp["WissKI instance"]
    Wisski[WissKI / SALZ]
    NCext[nextcloud_webdav_mount external]
    RedisMod[Redis Drupal module]
  end

  OIDC_D -.-> Realm
  UOIDC -.-> Realm
  GA -.-> Realm

4. Integration flows¶

4.1 Identity (OIDC)¶

sequenceDiagram
  participant U as Browser
  participant T as Traefik
  participant App as App (Manager / Drive / Code / …)
  participant KC as Keycloak

  U->>T: HTTPS Host(app)
  T->>App: proxy
  App->>U: redirect to Keycloak
  U->>KC: login / consent
  KC->>App: code / tokens (OIDC)
  App->>KC: userinfo (groups, gids, …)

4.2 Nextcloud ↔ JupyterHub / WissKI (FUSE mount)¶

SCS Manager owns mount lifecycle; Jupyter and WissKI only bind project Team Folder paths (rslave). Details: Nextcloud mount sidecar.

flowchart LR
  subgraph Host["Host FS"]
    Root["NEXTCLOUD_MOUNTS_ROOT<br/>/var/lib/scs/nextcloud-mounts<br/>propagation: shared"]
  end

  NC[nextcloud--nextcloud--app<br/>WebDAV]
  Mounter[nextcloud-mounter<br/>rclone FUSE]
  Mgr[scs-manager--drupal<br/>rc API only]
  JH[Jupyter notebook<br/>…/nextcloud/project-label]
  WK[WissKI Drupal<br/>private://nextcloud]

  Mgr -->|mount/unmount| Mounter
  Mounter -->|WebDAV| NC
  Mounter -->|FUSE under user/| Root
  Root -->|rslave bind project folder| JH
  Root -->|rslave bind project folder| WK

4.3 SCS Manager ↔ Portainer ↔ WissKI¶

flowchart LR
  Mgr[SCS Manager] -->|Docker API via socket| Portainer
  Portainer -->|deploy compose| WissKI[WissKI stack]
  WissKI -->|SPARQL internal| AuthProxy[scs--authproxy]
  AuthProxy --> RDF4J[scs--rdf4j]
  WissKI --> MariaDB[(scs--database)]

5. Where configs live¶

flowchart TB
  ENV[".env / example-env<br/>COMPOSE_FILE, domains, secrets"]
  CC["00_custom_configs/<stack>/"]
  Scripts["01_scripts/<stack>/pre-install.*"]
  StackDir["<stack>/  (submodule + generated)"]

  ENV --> Compose["docker compose up"]
  CC -->|start.sh copies overrides| StackDir
  Scripts -->|envsubst / DB create| StackDir
  CC -->|Drupal PHP snippets, realm tpl,<br/>OIDC YAML tpl, nginx tpl, patches| StackDir

Overrides use ${SCS_ROOT_PATH}/… for host volume paths and volumes: !override / networks: !override where the base list must be replaced.

6. Bootstrap, scripts, backup & maintenance¶

Lifecycle¶

flowchart TD
  A[Clone + submodule init] --> B[cp example-env → .env]
  B --> C[setup-nextcloud-mounts.sh<br/>+ optional systemd unit]
  C --> D[./start.sh]
  D --> D1[reverse-proxy network]
  D --> D2[Copy compose overrides]
  D --> D3[Start scs--database]
  D --> D4[Run all pre-install scripts]
  D4 --> E[docker compose up -d]
  E --> F[Post-config checklist<br/>Keycloak clients, occ hooks if needed]
  F --> G[Ops: backups, updates, repair]

Script map (01_scripts/)¶

Entry point for first-time setup: ./start.sh at repo root. Day-2 backup: 01_scripts/global/backup-all-services.bash. Updates: Maintenance / Updates.

Docker service inventory (quick)¶

7. Networks & shared volumes¶

See also¶

• Service infrastructure overview — narrative wiring per stack
• Pre-start steps — what start.sh runs
• Post-configuration checklist
• SCS Manager user lifecycle
• Troubleshooting: Drive ↔ Jupyter