|
| 1 | +# S-CORE DevContainer Architecture |
| 2 | + |
| 3 | +This document explains how the S-CORE DevContainer is designed, build and what its requirements are. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +One has to take ones own medicin and for that reason the [S-CORE devcontainer](../src/) is developed using another [simpler devcontainer](../.devcontainer). |
| 8 | + |
| 9 | +``` |
| 10 | + Host |
| 11 | + │ |
| 12 | + ▼ |
| 13 | +┌───────────────────────────────────────────────────────────────────────┐ |
| 14 | +│ Outer Dev Container (.devcontainer) │ |
| 15 | +│ Base: devcontainers/javascript-node │ |
| 16 | +│ Tools: devcontainer CLI, Docker CLI │ |
| 17 | +│ │ |
| 18 | +│ devcontainer build (scripts/build.sh) │ |
| 19 | +│ │ │ |
| 20 | +│ │ invokes docker build │ |
| 21 | +│ ▼ │ |
| 22 | +│ ┌─────────────────────────────────────────────────────────────────┐ │ |
| 23 | +│ │ Build S-CORE DevContainer (src/s-core-devcontainer) │ │ |
| 24 | +│ │ - Dockerfile (Ubuntu base image) │ │ |
| 25 | +│ │ - Pre-existing features (Git, LLVM/Clang, Rust, …) │ │ |
| 26 | +│ │ - S-CORE local feature (mounted at /devcontainer/features/…) │ │ |
| 27 | +│ └─────────────────────────────────────────────────────────────────┘ │ |
| 28 | +│ │ │ |
| 29 | +│ ▼ run validation (scripts/test.sh) │ |
| 30 | +│ │ │ |
| 31 | +│ │ on success | |
| 32 | +│ ▼ | |
| 33 | +│ Publish image → ghcr.io/eclipse-score/devcontainer:<tag> | |
| 34 | +└───────────────────────────────────────────────────────────────────────┘ |
| 35 | +``` |
| 36 | + |
| 37 | +This [simpler devcontainer](../.devcontainer) must be able to run [the devcontainer command](https://github.com/devcontainers/cli), which is a nodejs application and Docker. |
| 38 | +To achieve that [javascript-node](https://github.com/devcontainers/images/tree/main/src/javascript-node) as base image and the [Docker-in-Docker](https://github.com/devcontainers/features/tree/main/src/docker-in-docker) were chosen. |
| 39 | + |
| 40 | +## The S-CORE DevContainer |
| 41 | + |
| 42 | +[DR-001-Infra: Integration Strategy for External Development Tools](https://github.com/eclipse-score/score/blob/main/docs/design_decisions/DR-001-infra.md) |
| 43 | +and |
| 44 | +[DR-003-Infra: Devcontainer Strategy for S-CORE](https://github.com/eclipse-score/score/blob/main/docs/design_decisions/DR-003-infra.md) |
| 45 | +require that all tools / code inside the devcontainer are pinned and that it will be used by developers and CI. |
| 46 | +Developers and CI should only need to download prebuild container images. |
| 47 | +The container images should be able to build all of S-CORE without extra setup. |
| 48 | +This requires that the needed tools are preinstalled, but not too much to keep download times in check. |
| 49 | + |
| 50 | +To achieve this a small base image [based on Ubuntu is chosen](https://github.com/docker-library/buildpack-deps/blob/master/ubuntu/noble/curl/Dockerfile). |
| 51 | +To this image via either pre-existing devcontainer or our own S-CORE feature the tools needed to build S-CORE and run its tests are added. |
| 52 | +The tools also need to support IDEs like enabling code completion. |
| 53 | +All of these tools could have been added via a Dockerfile as well, but features are the mechanism to achieve composable devcontainer implementations and are preferred instead. |
| 54 | + |
| 55 | +The decision whether to use pre-existing feature or to add a tool using the S-CORE feature is based on the tradeoff between build time and maintainability. |
| 56 | +The chosen features are installed quickly, without us having to maintain them. |
| 57 | +Other tools installed via the S-CORE either have no corresponding feature, or their feature took so much time to install, that it was quicker done using our own code. |
| 58 | + |
| 59 | +### Proxy environments |
| 60 | + |
| 61 | +To support proxy environments environment variables are set in the [Dockerfile](../src/s-core-devcontainer/.devcontainer/Dockerfile) and unset if empty to not interfere with non proxy environments. |
| 62 | + |
| 63 | +## Tests |
| 64 | + |
| 65 | +After an image build tests check, that each tool expected to be in the image is installed with the specified version for [pre-existing features](../src/s-core-devcontainer/test-project/test.sh) and the [S-CORE feature](../src/s-core-devcontainer/.devcontainer/s-core-local/tests/test_default.sh). |
| 66 | + |
| 67 | +However it is not tested, if S-CORE can be build with that image. |
| 68 | +The expectation is that pinned devcontainer versions are used by S-CORE repos and when an image update fails to build a certain module its version bump pull request will fail CI. |
| 69 | + |
| 70 | +## Why this setup |
| 71 | + |
| 72 | +This setup is predictable and fast because a pre-built image avoids per-repo Docker builds and ensures everyone shares the same toolchain. |
| 73 | +It strengthens the supply chain by pinning versions and hashes, sourcing features from trusted catalogs, and gating publication via CI builds and tests. |
| 74 | +It also enforces a clear separation of concerns: general tooling is delivered through reusable features, S-CORE–specific logic lives in a dedicated feature, and image composition plus publishing are centralized. |
0 commit comments