container-superposition 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (184) hide show
  1. package/README.md +3 -0
  2. package/dist/tool/cli/args.d.ts.map +1 -1
  3. package/dist/tool/cli/args.js +1 -1
  4. package/dist/tool/cli/args.js.map +1 -1
  5. package/dist/tool/commands/adopt.d.ts.map +1 -1
  6. package/dist/tool/commands/adopt.js +15 -21
  7. package/dist/tool/commands/adopt.js.map +1 -1
  8. package/dist/tool/commands/doctor.d.ts +1 -0
  9. package/dist/tool/commands/doctor.d.ts.map +1 -1
  10. package/dist/tool/commands/doctor.js +1370 -73
  11. package/dist/tool/commands/doctor.js.map +1 -1
  12. package/dist/tool/questionnaire/composer.d.ts +3 -1
  13. package/dist/tool/questionnaire/composer.d.ts.map +1 -1
  14. package/dist/tool/questionnaire/composer.js +273 -20
  15. package/dist/tool/questionnaire/composer.js.map +1 -1
  16. package/dist/tool/questionnaire/presets.d.ts.map +1 -1
  17. package/dist/tool/questionnaire/presets.js +1 -0
  18. package/dist/tool/questionnaire/presets.js.map +1 -1
  19. package/dist/tool/questionnaire/questionnaire.d.ts.map +1 -1
  20. package/dist/tool/questionnaire/questionnaire.js +3 -1
  21. package/dist/tool/questionnaire/questionnaire.js.map +1 -1
  22. package/dist/tool/schema/project-config.d.ts.map +1 -1
  23. package/dist/tool/schema/project-config.js +174 -1
  24. package/dist/tool/schema/project-config.js.map +1 -1
  25. package/dist/tool/schema/types.d.ts +53 -2
  26. package/dist/tool/schema/types.d.ts.map +1 -1
  27. package/docs/README.md +1 -0
  28. package/docs/overlays.md +188 -147
  29. package/docs/specs/001-verbose-plan-graph/spec.md +5 -12
  30. package/docs/specs/002-superposition-config-file/spec.md +5 -12
  31. package/docs/specs/003-mkdocs2-overlay/spec.md +2 -9
  32. package/docs/specs/004-doctor-fix/spec.md +1 -8
  33. package/docs/specs/005-cuda-overlay/spec.md +2 -9
  34. package/docs/specs/006-rocm-overlay/spec.md +3 -10
  35. package/docs/specs/007-target-aware-generation/spec.md +4 -11
  36. package/docs/specs/008-project-file-canonical/spec.md +7 -8
  37. package/docs/specs/009-project-env/spec.md +3 -10
  38. package/docs/specs/010-compose-env-materialization/spec.md +3 -10
  39. package/docs/specs/011-overlay-parameters/spec.md +2 -9
  40. package/docs/specs/012-ollama-cli-overlay/spec.md +47 -0
  41. package/docs/specs/013-doctor-dependency-check/spec.md +250 -0
  42. package/docs/specs/014-doctor-compose-port-cross-validation/spec.md +276 -0
  43. package/docs/specs/015-doctor-env-example-drift/spec.md +248 -0
  44. package/docs/specs/016-doctor-reproducibility-check/spec.md +276 -0
  45. package/docs/specs/017-doctor-dry-run/spec.md +276 -0
  46. package/docs/specs/{007-init-project-file → 018-init-project-file}/spec.md +2 -9
  47. package/docs/specs/019-project-mounts/spec.md +176 -0
  48. package/docs/specs/taxonomy.md +186 -0
  49. package/docs/superposition-yml.md +467 -0
  50. package/overlays/.presets/full-observability.yml +113 -0
  51. package/overlays/.presets/k8s-dev.yml +174 -0
  52. package/overlays/.presets/local-llm.yml +105 -0
  53. package/overlays/.presets/vector-ai.yml +150 -0
  54. package/overlays/.shared/vscode/js-ts-settings.json +19 -0
  55. package/overlays/.shared/vscode/markdown-extensions.json +8 -0
  56. package/overlays/alertmanager/devcontainer.patch.json +0 -1
  57. package/overlays/alertmanager/docker-compose.yml +8 -0
  58. package/overlays/alertmanager/overlay.yml +1 -0
  59. package/overlays/amp/devcontainer.patch.json +4 -1
  60. package/overlays/ansible/README.md +163 -0
  61. package/overlays/ansible/devcontainer.patch.json +14 -0
  62. package/overlays/ansible/overlay.yml +18 -0
  63. package/overlays/argocd/README.md +158 -0
  64. package/overlays/argocd/devcontainer.patch.json +9 -0
  65. package/overlays/argocd/overlay.yml +17 -0
  66. package/overlays/argocd/setup.sh +29 -0
  67. package/overlays/argocd/verify.sh +14 -0
  68. package/overlays/bun/devcontainer.patch.json +1 -10
  69. package/overlays/bun/overlay.yml +8 -1
  70. package/overlays/claude-code/devcontainer.patch.json +6 -1
  71. package/overlays/codex/devcontainer.patch.json +5 -0
  72. package/overlays/comfyui/docker-compose.yml +1 -0
  73. package/overlays/comfyui/overlay.yml +4 -0
  74. package/overlays/commitlint/devcontainer.patch.json +1 -6
  75. package/overlays/docker-sock/overlay.yml +1 -0
  76. package/overlays/dotnet/overlay.yml +4 -1
  77. package/overlays/fuseki/.env.example +5 -0
  78. package/overlays/fuseki/README.md +173 -0
  79. package/overlays/fuseki/devcontainer.patch.json +18 -0
  80. package/overlays/fuseki/docker-compose.yml +29 -0
  81. package/overlays/fuseki/overlay.yml +42 -0
  82. package/overlays/fuseki/verify.sh +58 -0
  83. package/overlays/gemini-cli/devcontainer.patch.json +4 -1
  84. package/overlays/go/overlay.yml +6 -1
  85. package/overlays/grafana/devcontainer.patch.json +0 -1
  86. package/overlays/grafana/docker-compose.yml +8 -2
  87. package/overlays/grafana/overlay.yml +6 -1
  88. package/overlays/jaeger/.env.example +11 -0
  89. package/overlays/jaeger/README.md +33 -4
  90. package/overlays/jaeger/devcontainer.patch.json +9 -1
  91. package/overlays/jaeger/docker-compose.yml +17 -0
  92. package/overlays/jaeger/overlay.yml +1 -12
  93. package/overlays/java/overlay.yml +6 -1
  94. package/overlays/jupyter/docker-compose.yml +1 -0
  95. package/overlays/jupyter/overlay.yml +1 -0
  96. package/overlays/keycloak/devcontainer.patch.json +0 -1
  97. package/overlays/keycloak/docker-compose.yml +1 -0
  98. package/overlays/keycloak/overlay.yml +15 -0
  99. package/overlays/localstack/docker-compose.yml +1 -0
  100. package/overlays/localstack/overlay.yml +19 -1
  101. package/overlays/loki/devcontainer.patch.json +0 -1
  102. package/overlays/loki/docker-compose.yml +8 -0
  103. package/overlays/loki/overlay.yml +1 -0
  104. package/overlays/mailpit/docker-compose.yml +1 -0
  105. package/overlays/mailpit/overlay.yml +1 -0
  106. package/overlays/minio/devcontainer.patch.json +1 -1
  107. package/overlays/minio/docker-compose.yml +1 -0
  108. package/overlays/minio/overlay.yml +23 -2
  109. package/overlays/mkdocs/devcontainer.patch.json +1 -5
  110. package/overlays/mkdocs/overlay.yml +3 -1
  111. package/overlays/mkdocs2/devcontainer.patch.json +1 -5
  112. package/overlays/mkdocs2/overlay.yml +2 -0
  113. package/overlays/mongodb/docker-compose.yml +2 -0
  114. package/overlays/mongodb/overlay.yml +26 -2
  115. package/overlays/mysql/docker-compose.yml +2 -0
  116. package/overlays/mysql/overlay.yml +36 -2
  117. package/overlays/nats/docker-compose.yml +1 -0
  118. package/overlays/nats/overlay.yml +18 -2
  119. package/overlays/nodejs/devcontainer.patch.json +1 -12
  120. package/overlays/nodejs/overlay.yml +8 -1
  121. package/overlays/ollama/README.md +4 -3
  122. package/overlays/ollama/docker-compose.yml +1 -0
  123. package/overlays/ollama/overlay.yml +6 -1
  124. package/overlays/ollama/verify.sh +5 -28
  125. package/overlays/ollama-cli/README.md +90 -0
  126. package/overlays/ollama-cli/devcontainer.patch.json +3 -0
  127. package/overlays/ollama-cli/overlay.yml +19 -0
  128. package/overlays/{ollama → ollama-cli}/setup.sh +7 -10
  129. package/overlays/ollama-cli/verify.sh +49 -0
  130. package/overlays/open-webui/docker-compose.yml +1 -0
  131. package/overlays/open-webui/overlay.yml +8 -1
  132. package/overlays/opencode/devcontainer.patch.json +4 -1
  133. package/overlays/otel-collector/README.md +4 -0
  134. package/overlays/otel-collector/devcontainer.patch.json +4 -1
  135. package/overlays/otel-collector/docker-compose.yml +8 -4
  136. package/overlays/otel-collector/overlay.yml +1 -0
  137. package/overlays/otel-demo-nodejs/devcontainer.patch.json +0 -1
  138. package/overlays/otel-demo-nodejs/docker-compose.yml +1 -0
  139. package/overlays/otel-demo-nodejs/overlay.yml +9 -1
  140. package/overlays/otel-demo-python/devcontainer.patch.json +0 -1
  141. package/overlays/otel-demo-python/docker-compose.yml +1 -0
  142. package/overlays/otel-demo-python/overlay.yml +6 -1
  143. package/overlays/pandoc/README.md +10 -0
  144. package/overlays/pandoc/devcontainer.patch.json +0 -5
  145. package/overlays/pandoc/overlay.yml +2 -0
  146. package/overlays/pandoc/setup.sh +10 -0
  147. package/overlays/pgvector/devcontainer.patch.json +11 -5
  148. package/overlays/pgvector/docker-compose.yml +1 -0
  149. package/overlays/pgvector/overlay.yml +3 -0
  150. package/overlays/playwright/devcontainer.patch.json +0 -5
  151. package/overlays/playwright/overlay.yml +2 -1
  152. package/overlays/postgres/docker-compose.yml +1 -0
  153. package/overlays/postgres/overlay.yml +4 -1
  154. package/overlays/pre-commit/devcontainer.patch.json +1 -7
  155. package/overlays/prometheus/devcontainer.patch.json +0 -1
  156. package/overlays/prometheus/docker-compose.yml +8 -0
  157. package/overlays/prometheus/overlay.yml +1 -0
  158. package/overlays/promtail/devcontainer.patch.json +1 -2
  159. package/overlays/promtail/docker-compose.yml +8 -0
  160. package/overlays/promtail/overlay.yml +1 -0
  161. package/overlays/qdrant/docker-compose.yml +1 -0
  162. package/overlays/qdrant/overlay.yml +5 -1
  163. package/overlays/rabbitmq/docker-compose.yml +1 -0
  164. package/overlays/rabbitmq/overlay.yml +25 -2
  165. package/overlays/redis/docker-compose.yml +7 -0
  166. package/overlays/redis/overlay.yml +15 -1
  167. package/overlays/redpanda/docker-compose.yml +1 -0
  168. package/overlays/redpanda/overlay.yml +15 -3
  169. package/overlays/rocm/overlay.yml +2 -1
  170. package/overlays/rust/overlay.yml +3 -1
  171. package/overlays/sqlserver/docker-compose.yml +1 -0
  172. package/overlays/sqlserver/overlay.yml +17 -0
  173. package/overlays/task/README.md +47 -0
  174. package/overlays/task/devcontainer.patch.json +9 -0
  175. package/overlays/task/overlay.yml +16 -0
  176. package/overlays/task/setup.sh +29 -0
  177. package/overlays/task/verify.sh +14 -0
  178. package/overlays/tempo/devcontainer.patch.json +0 -1
  179. package/overlays/tempo/docker-compose.yml +8 -0
  180. package/overlays/tempo/overlay.yml +1 -0
  181. package/overlays/windsurf-cli/devcontainer.patch.json +4 -1
  182. package/package.json +1 -1
  183. package/tool/schema/config.schema.json +74 -1
  184. package/overlays/.shared/otel/otel-base-config.yaml +0 -30
@@ -1,12 +1,28 @@
1
1
  id: nats
2
2
  name: NATS
3
3
  description: Lightweight pub/sub messaging with JetStream
4
- category: database
4
+ category: messaging
5
5
  supports:
6
6
  - compose
7
7
  requires: []
8
- suggests: []
8
+ suggests:
9
+ - prometheus
10
+ - grafana
9
11
  conflicts: []
12
+ serviceOrder: 0
13
+ parameters:
14
+ NATS_VERSION:
15
+ description: NATS image version tag
16
+ default: '2'
17
+ NATS_CLIENT_PORT:
18
+ description: Host port mapped to NATS client (4222 inside container)
19
+ default: '4222'
20
+ NATS_HTTP_PORT:
21
+ description: Host port mapped to NATS monitoring HTTP (8222 inside container)
22
+ default: '8222'
23
+ NATS_CLUSTER_PORT:
24
+ description: Host port mapped to NATS cluster (6222 inside container)
25
+ default: '6222'
10
26
  tags:
11
27
  - database
12
28
  - messaging
@@ -13,21 +13,10 @@
13
13
  },
14
14
  "customizations": {
15
15
  "vscode": {
16
- "extensions": [
17
- "dbaeumer.vscode-eslint",
18
- "esbenp.prettier-vscode",
19
- "christian-kohler.npm-intellisense"
20
- ],
16
+ "extensions": ["christian-kohler.npm-intellisense"],
21
17
  "settings": {
22
- "editor.defaultFormatter": "esbenp.prettier-vscode",
23
18
  "editor.codeActionsOnSave": {
24
19
  "source.fixAll.eslint": "explicit"
25
- },
26
- "[typescript]": {
27
- "editor.defaultFormatter": "esbenp.prettier-vscode"
28
- },
29
- "[javascript]": {
30
- "editor.defaultFormatter": "esbenp.prettier-vscode"
31
20
  }
32
21
  }
33
22
  }
@@ -5,10 +5,17 @@ category: language
5
5
  supports: []
6
6
  requires: []
7
7
  suggests: []
8
- conflicts: []
8
+ conflicts:
9
+ - grafana
10
+ - open-webui
11
+ - mysql
12
+ - redpanda
13
+ - otel-demo-nodejs
9
14
  tags:
10
15
  - language
11
16
  - nodejs
12
17
  - javascript
13
18
  - typescript
14
19
  ports: []
20
+ imports:
21
+ - .shared/vscode/js-ts-settings.json
@@ -1,6 +1,6 @@
1
1
  # Ollama Overlay
2
2
 
3
- Runs [Ollama](https://ollama.com) as a Docker Compose service inside the devcontainer, enabling local LLM inference without leaving the dev environment. The Ollama CLI is also installed directly in the devcontainer for ergonomic model management and inference from the terminal.
3
+ Runs [Ollama](https://ollama.com) as a Docker Compose service inside the devcontainer, enabling local LLM inference without leaving the dev environment. This overlay automatically requires `ollama-cli`, so the Ollama CLI is also available in the devcontainer terminal.
4
4
 
5
5
  ## Features
6
6
 
@@ -25,7 +25,7 @@ Ollama runs as a long-lived Docker Compose service (`ollama`) alongside your dev
25
25
 
26
26
  The `OLLAMA_HOST` environment variable is set to `http://ollama:11434` in the devcontainer, so the Ollama CLI and any tools that respect this variable will connect to the sidecar automatically.
27
27
 
28
- The `setup.sh` script installs the Ollama CLI directly in the devcontainer at container creation time, providing the full `ollama` UX from the terminal. In the normal compose-based case it copies `/usr/bin/ollama` from the already-running `ollama/ollama` sidecar image, avoiding a second multi-gigabyte download. If Docker is unavailable, it falls back to the official Linux release archives (`.tar.zst`, with legacy `.tgz` fallback). The CLI is client-only and does not start a daemon inside the devcontainer.
28
+ The Ollama CLI installation is provided by the required [`ollama-cli`](../ollama-cli/README.md) overlay. This keeps service responsibilities (`ollama`) and CLI responsibilities (`ollama-cli`) separated while preserving the same day-to-day user experience.
29
29
 
30
30
  ## Mapping Host Models into the Container
31
31
 
@@ -58,7 +58,7 @@ The mount is read-write by default, so `ollama pull` inside the container also s
58
58
 
59
59
  ## Using the Ollama CLI
60
60
 
61
- The Ollama CLI is installed directly in the devcontainer by `setup.sh`. The `OLLAMA_HOST` environment variable is pre-configured to `http://ollama:11434`, so all commands automatically target the sidecar — no manual configuration required.
61
+ The Ollama CLI is installed via the required `ollama-cli` overlay. The `OLLAMA_HOST` environment variable is pre-configured to `http://ollama:11434`, so all commands automatically target the sidecar — no manual configuration required.
62
62
 
63
63
  ```bash
64
64
  # From the main devcontainer terminal — talks to the sidecar
@@ -320,6 +320,7 @@ docker compose restart ollama
320
320
 
321
321
  - [`cuda`](../cuda/README.md) — NVIDIA GPU passthrough for faster inference
322
322
  - [`rocm`](../rocm/README.md) — AMD GPU passthrough for faster inference
323
+ - [`ollama-cli`](../ollama-cli/README.md) — Ollama CLI-only overlay (works in plain stacks and is auto-required here)
323
324
  - [`codex`](../codex/README.md) — OpenAI Codex CLI (can use local endpoint)
324
325
  - [`claude-code`](../claude-code/README.md) — Anthropic Claude CLI
325
326
  - [`amp`](../amp/README.md) — Sourcegraph Amp CLI
@@ -22,3 +22,4 @@ services:
22
22
 
23
23
  networks:
24
24
  devnet:
25
+ name: devnet
@@ -4,12 +4,17 @@ description: Local LLM inference server with OpenAI-compatible API
4
4
  category: dev
5
5
  supports:
6
6
  - compose
7
- requires: []
7
+ requires:
8
+ - ollama-cli
8
9
  suggests:
9
10
  - codex
10
11
  - claude-code
11
12
  - amp
13
+ - prometheus
14
+ - grafana
15
+ - otel-collector
12
16
  conflicts: []
17
+ serviceOrder: 3
13
18
  tags:
14
19
  - dev
15
20
  - ai
@@ -1,25 +1,15 @@
1
1
  #!/bin/bash
2
2
  # Verification script for Ollama overlay
3
- # Confirms Ollama CLI is installed and sidecar service is running and accessible
3
+ # Confirms Ollama sidecar service is running and accessible
4
4
 
5
5
  set -e
6
6
 
7
7
  echo "🔍 Verifying Ollama overlay..."
8
8
  echo ""
9
9
 
10
- # Check Ollama CLI is installed
11
- echo "1️⃣ Checking Ollama CLI..."
12
- if ! command -v ollama &>/dev/null; then
13
- echo " ❌ ollama CLI not found"
14
- echo ""
15
- echo "❌ Ollama overlay verification failed (ollama CLI is required but not installed)"
16
- exit 1
17
- fi
18
- echo " ✅ ollama CLI found: $(ollama --version 2>/dev/null || echo 'version unavailable')"
19
-
20
10
  # Check OLLAMA_HOST is set
21
11
  echo ""
22
- echo "2️⃣ Checking OLLAMA_HOST..."
12
+ echo "1️⃣ Checking OLLAMA_HOST..."
23
13
  if [[ -z "${OLLAMA_HOST:-}" ]]; then
24
14
  echo " ⚠️ OLLAMA_HOST is not set — CLI will target localhost instead of the sidecar"
25
15
  else
@@ -28,7 +18,7 @@ fi
28
18
 
29
19
  # Check if curl is available
30
20
  echo ""
31
- echo "3️⃣ Checking curl availability..."
21
+ echo "2️⃣ Checking curl availability..."
32
22
  if ! command -v curl &> /dev/null; then
33
23
  echo " ❌ curl not found"
34
24
  echo ""
@@ -39,7 +29,7 @@ echo " ✅ curl found"
39
29
 
40
30
  # Check Ollama API
41
31
  echo ""
42
- echo "4️⃣ Checking Ollama service..."
32
+ echo "3️⃣ Checking Ollama service..."
43
33
  OLLAMA_HOST="${OLLAMA_HOST:-http://ollama:11434}"
44
34
  OLLAMA_READY=false
45
35
 
@@ -61,21 +51,9 @@ if [ "$OLLAMA_READY" = false ]; then
61
51
  exit 1
62
52
  fi
63
53
 
64
- # Smoke-test CLI against the sidecar
65
- echo ""
66
- echo "5️⃣ Listing available models via CLI..."
67
- set +e
68
- ollama list && echo " ✅ ollama CLI can reach sidecar at ${OLLAMA_HOST}"
69
- CLI_STATUS=$?
70
- set -e
71
-
72
- if [ $CLI_STATUS -ne 0 ]; then
73
- echo " ⚠️ ollama CLI could not reach sidecar at ${OLLAMA_HOST}"
74
- fi
75
-
76
54
  # Show available models via REST API
77
55
  echo ""
78
- echo "6️⃣ Listing available models via API..."
56
+ echo "4️⃣ Listing available models via API..."
79
57
  TAGS_JSON=$(curl -sf "${OLLAMA_HOST}/api/tags")
80
58
  CURL_STATUS=$?
81
59
  if [ $CURL_STATUS -ne 0 ]; then
@@ -96,4 +74,3 @@ echo ""
96
74
  echo "✅ Ollama overlay verification complete"
97
75
  echo " API endpoint: ${OLLAMA_HOST}"
98
76
  echo " Docs: https://ollama.com/library"
99
-
@@ -0,0 +1,90 @@
1
+ # Ollama CLI Overlay
2
+
3
+ Installs the [Ollama](https://ollama.com) command-line client in your devcontainer so you can use Ollama models from terminal tools without running an Ollama sidecar in the same compose stack.
4
+
5
+ ## Features
6
+
7
+ - **Ollama CLI in devcontainer** — Run `ollama pull / run / list / rm` from the main container
8
+ - **Works in plain and compose stacks** — Can be used without a local Ollama service overlay
9
+ - **Remote-server friendly** — Supports connecting to host or external Ollama endpoints via `OLLAMA_HOST`
10
+ - **Fast install path** — Prefers extracting `/usr/bin/ollama` from local `ollama/ollama` Docker image when available
11
+ - **Archive fallback** — Falls back to official Linux release archives (`.tar.zst`, then legacy `.tgz`)
12
+
13
+ ## How It Works
14
+
15
+ This overlay installs only the Ollama CLI binary in the devcontainer. It does **not** run `ollama serve` or create a compose service.
16
+
17
+ By default, the CLI targets `http://localhost:11434` unless `OLLAMA_HOST` is set. Set `OLLAMA_HOST` to point at your reachable Ollama server (host machine, sidecar, or remote endpoint).
18
+
19
+ ## Configuration
20
+
21
+ Set `OLLAMA_HOST` in your devcontainer environment when needed:
22
+
23
+ ```bash
24
+ # Example: host Ollama server
25
+ export OLLAMA_HOST=http://host.docker.internal:11434
26
+
27
+ # Example: remote Ollama server
28
+ export OLLAMA_HOST=http://10.0.0.50:11434
29
+ ```
30
+
31
+ You can also set this in `devcontainer.json` (`containerEnv`/`remoteEnv`) or your shell profile.
32
+
33
+ ## Common Commands
34
+
35
+ ```bash
36
+ # Show CLI version
37
+ ollama --version
38
+
39
+ # Point to a specific server for one command
40
+ OLLAMA_HOST=http://host.docker.internal:11434 ollama list
41
+
42
+ # Pull and run models
43
+ ollama pull llama3.2
44
+ ollama run llama3.2 "explain this function"
45
+
46
+ # Model management
47
+ ollama list
48
+ ollama show llama3.2
49
+ ollama rm llama3.2
50
+ ```
51
+
52
+ ## Use Cases
53
+
54
+ - **Use host Ollama from containerized tooling** — Keep Ollama running on host, use CLI in devcontainer
55
+ - **Agent tooling integration** — Pair with `codex`, `claude-code`, or `amp` overlays while pointing at existing Ollama infrastructure
56
+ - **Remote inference endpoints** — Work against Ollama servers running on another machine or VM
57
+
58
+ **Integrates well with:**
59
+
60
+ - `ollama` — Compose sidecar server (this overlay is auto-required there)
61
+ - `codex` — OpenAI Codex CLI
62
+ - `claude-code` — Anthropic Claude Code CLI
63
+ - `amp` — Sourcegraph Amp CLI
64
+
65
+ ## Troubleshooting
66
+
67
+ ### `ollama` command not found
68
+
69
+ ```bash
70
+ which ollama
71
+ ollama --version
72
+ ```
73
+
74
+ If missing, rebuild the container so `setup.sh` runs again.
75
+
76
+ ### Cannot reach Ollama endpoint
77
+
78
+ ```bash
79
+ echo "$OLLAMA_HOST"
80
+ curl -v "$OLLAMA_HOST/api/tags"
81
+ ```
82
+
83
+ Verify network reachability from inside the devcontainer and ensure the Ollama server is running.
84
+
85
+ ## References
86
+
87
+ - [Ollama Official Website](https://ollama.com)
88
+ - [Ollama Model Library](https://ollama.com/library)
89
+ - [Ollama REST API Documentation](https://github.com/ollama/ollama/blob/main/docs/api.md)
90
+ - [Ollama OpenAI Compatibility](https://github.com/ollama/ollama/blob/main/docs/openai.md)
@@ -0,0 +1,3 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
3
+ }
@@ -0,0 +1,19 @@
1
+ id: ollama-cli
2
+ name: Ollama CLI
3
+ description: Ollama command-line client for local or remote Ollama servers
4
+ category: dev
5
+ supports: []
6
+ requires: []
7
+ suggests:
8
+ - ollama
9
+ - codex
10
+ - claude-code
11
+ - amp
12
+ conflicts: []
13
+ tags:
14
+ - dev
15
+ - ai
16
+ - llm
17
+ - ollama
18
+ - cli
19
+ ports: []
@@ -1,7 +1,6 @@
1
1
  #!/bin/bash
2
2
  # Ollama CLI setup script
3
- # Installs the Ollama CLI in the devcontainer so developers can manage models
4
- # and run inference from the terminal, targeting the ollama sidecar service.
3
+ # Installs the Ollama CLI in the devcontainer for local or remote Ollama usage.
5
4
 
6
5
  set -e
7
6
 
@@ -11,14 +10,13 @@ detect_arch
11
10
 
12
11
  if command_exists ollama; then
13
12
  echo "✓ Ollama CLI already installed: $(ollama --version)"
14
- echo "ℹ️ OLLAMA_HOST is set to ${OLLAMA_HOST:-http://ollama:11434} — all commands target the sidecar."
13
+ echo "ℹ️ OLLAMA_HOST=${OLLAMA_HOST:-http://localhost:11434}"
15
14
  exit 0
16
15
  fi
17
16
 
18
17
  echo "📦 Installing Ollama CLI..."
19
- # Prefer copying the CLI binary from the already-present Ollama sidecar image.
20
- # Compose-based templates include docker-outside-of-docker, so this avoids
21
- # re-downloading the multi-GB upstream Linux release archive in normal use.
18
+ # Prefer copying the CLI binary from a local Ollama Docker image when available.
19
+ # This avoids downloading large release archives in Docker-enabled environments.
22
20
  OLLAMA_IMAGE="ollama/ollama:${OLLAMA_VERSION:-latest}"
23
21
  if command_exists docker && docker info >/dev/null 2>&1; then
24
22
  tmpdir=$(mktemp -d)
@@ -46,9 +44,8 @@ if command_exists docker && docker info >/dev/null 2>&1; then
46
44
  fi
47
45
 
48
46
  if ! command_exists ollama; then
49
- # Fallback to official release archives without invoking the full
50
- # install.sh flow, which configures a local daemon/service that the
51
- # devcontainer does not need because the sidecar already provides the API.
47
+ # Fallback to official release archives without invoking the full install.sh
48
+ # flow, which configures a local daemon/service.
52
49
  OLLAMA_DOWNLOAD_BASE="https://ollama.com/download/ollama-linux-${CS_ARCH}"
53
50
 
54
51
  if curl -fsSLI "${OLLAMA_DOWNLOAD_BASE}.tar.zst" >/dev/null 2>&1; then
@@ -103,4 +100,4 @@ if ! command_exists ollama; then
103
100
  fi
104
101
 
105
102
  echo "✓ Ollama CLI installed: $(ollama --version)"
106
- echo "ℹ️ OLLAMA_HOST is set to ${OLLAMA_HOST:-http://ollama:11434} — all commands target the sidecar."
103
+ echo "ℹ️ Configure OLLAMA_HOST to target your server (current: ${OLLAMA_HOST:-http://localhost:11434})"
@@ -0,0 +1,49 @@
1
+ #!/bin/bash
2
+ # Verification script for Ollama CLI overlay
3
+
4
+ set -e
5
+
6
+ echo "🔍 Verifying Ollama CLI overlay..."
7
+ echo ""
8
+
9
+ echo "1️⃣ Checking Ollama CLI..."
10
+ if ! command -v ollama &>/dev/null; then
11
+ echo " ❌ ollama CLI not found"
12
+ echo ""
13
+ echo "❌ Ollama CLI overlay verification failed"
14
+ exit 1
15
+ fi
16
+ echo " ✅ ollama CLI found: $(ollama --version 2>/dev/null || echo 'version unavailable')"
17
+
18
+ echo ""
19
+ echo "2️⃣ Checking OLLAMA_HOST configuration..."
20
+ if [[ -z "${OLLAMA_HOST:-}" ]]; then
21
+ echo " ℹ️ OLLAMA_HOST is not set (default CLI target: http://localhost:11434)"
22
+ echo " ℹ️ Set OLLAMA_HOST to a reachable Ollama endpoint, e.g. http://host.docker.internal:11434"
23
+ echo ""
24
+ echo "✅ Ollama CLI overlay verification complete"
25
+ exit 0
26
+ fi
27
+
28
+ echo " ✅ OLLAMA_HOST=${OLLAMA_HOST}"
29
+
30
+ echo ""
31
+ echo "3️⃣ Checking endpoint reachability (best effort)..."
32
+ if ! command -v curl &>/dev/null; then
33
+ echo " ⚠️ curl not found; skipping endpoint check"
34
+ echo ""
35
+ echo "✅ Ollama CLI overlay verification complete"
36
+ exit 0
37
+ fi
38
+
39
+ set +e
40
+ if curl -sf "${OLLAMA_HOST}/api/tags" >/dev/null; then
41
+ echo " ✅ Reached Ollama endpoint at ${OLLAMA_HOST}"
42
+ else
43
+ echo " ⚠️ Could not reach ${OLLAMA_HOST}/api/tags"
44
+ echo " ⚠️ Ensure your Ollama server is running and reachable from the devcontainer"
45
+ fi
46
+ set -e
47
+
48
+ echo ""
49
+ echo "✅ Ollama CLI overlay verification complete"
@@ -21,3 +21,4 @@ volumes:
21
21
 
22
22
  networks:
23
23
  devnet:
24
+ name: devnet
@@ -7,7 +7,14 @@ supports:
7
7
  requires: []
8
8
  suggests:
9
9
  - ollama
10
- conflicts: []
10
+ - prometheus
11
+ - otel-collector
12
+ conflicts:
13
+ - grafana
14
+ - nodejs
15
+ - bun
16
+ - rust
17
+ serviceOrder: 3
11
18
  tags:
12
19
  - dev
13
20
  - ai
@@ -1,3 +1,6 @@
1
1
  {
2
- "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
2
+ "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
3
+ "postCreateCommand": {
4
+ "setup-opencode": "bash .devcontainer/scripts/setup-opencode.sh"
5
+ }
3
6
  }
@@ -45,6 +45,10 @@ graph TD
45
45
  - `8889` - Prometheus exporter endpoint (scrape target)
46
46
  - `13133` - Health check extension
47
47
 
48
+ ### Pre-configured OpenTelemetry Environment
49
+
50
+ When this overlay is selected, the devcontainer's `OTEL_EXPORTER_OTLP_ENDPOINT` is automatically set to `http://otel-collector:4317` so that any properly-instrumented app sends telemetry to the collector. If the **jaeger** overlay is also selected, the collector overlay takes precedence (it is applied later) and correctly routes telemetry through the collector pipeline to Jaeger.
51
+
48
52
  ### Environment Variables
49
53
 
50
54
  The overlay includes a `.env.example` file. Copy it to `.env` and customize:
@@ -1,7 +1,6 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
3
3
  "runServices": ["otel-collector"],
4
- "_serviceOrder": 2,
5
4
  "forwardPorts": [4317, 4318, 8888, 8889, 13133],
6
5
  "portsAttributes": {
7
6
  "4317": {
@@ -24,5 +23,9 @@
24
23
  "label": "Health Check",
25
24
  "onAutoForward": "silent"
26
25
  }
26
+ },
27
+ "remoteEnv": {
28
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "http://otel-collector:4317",
29
+ "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc"
27
30
  }
28
31
  }
@@ -2,6 +2,7 @@ version: '3.8'
2
2
  services:
3
3
  otel-collector:
4
4
  image: otel/opentelemetry-collector-contrib:${OTEL_COLLECTOR_VERSION:-latest}
5
+ restart: unless-stopped
5
6
  command: ['--config=/etc/otel-collector-config.yaml']
6
7
  volumes:
7
8
  - ./otel-collector-config-otel-collector.yaml:/etc/otel-collector-config.yaml
@@ -11,12 +12,15 @@ services:
11
12
  - '${OTEL_METRICS_PORT:-8888}:8888' # Prometheus metrics exposed by collector
12
13
  - '${OTEL_EXPORTER_PORT:-8889}:8889' # Prometheus exporter
13
14
  - '${OTEL_HEALTH_PORT:-13133}:13133' # health_check extension
14
- depends_on:
15
- - jaeger
16
- - prometheus
17
- - loki
18
15
  networks:
19
16
  - devnet
17
+ healthcheck:
18
+ test: ['CMD', 'wget', '-qO-', 'http://localhost:13133/']
19
+ interval: 10s
20
+ timeout: 5s
21
+ retries: 5
22
+ start_period: 10s
20
23
 
21
24
  networks:
22
25
  devnet:
26
+ name: devnet
@@ -19,5 +19,6 @@ ports:
19
19
  - 8888
20
20
  - 8889
21
21
  order: 2
22
+ serviceOrder: 2
22
23
  imports:
23
24
  - .shared/otel/instrumentation.env
@@ -1,7 +1,6 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
3
3
  "runServices": ["otel-demo-nodejs"],
4
- "_serviceOrder": 3,
5
4
  "forwardPorts": [8080],
6
5
  "portsAttributes": {
7
6
  "8080": {
@@ -17,3 +17,4 @@ services:
17
17
 
18
18
  networks:
19
19
  devnet:
20
+ name: devnet
@@ -12,7 +12,14 @@ suggests:
12
12
  - prometheus
13
13
  - loki
14
14
  - grafana
15
- conflicts: []
15
+ conflicts:
16
+ - mysql
17
+ - redpanda
18
+ - nodejs
19
+ - bun
20
+ - go
21
+ - java
22
+ - dotnet
16
23
  tags:
17
24
  - observability
18
25
  - demo
@@ -21,3 +28,4 @@ tags:
21
28
  ports:
22
29
  - 8080
23
30
  order: 4
31
+ serviceOrder: 4
@@ -1,7 +1,6 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
3
3
  "runServices": ["otel-demo-python"],
4
- "_serviceOrder": 3,
5
4
  "forwardPorts": [8081],
6
5
  "portsAttributes": {
7
6
  "8081": {
@@ -17,3 +17,4 @@ services:
17
17
 
18
18
  networks:
19
19
  devnet:
20
+ name: devnet
@@ -12,7 +12,11 @@ suggests:
12
12
  - prometheus
13
13
  - loki
14
14
  - grafana
15
- conflicts: []
15
+ conflicts:
16
+ - mongodb
17
+ - redpanda
18
+ - go
19
+ - java
16
20
  tags:
17
21
  - observability
18
22
  - demo
@@ -21,3 +25,4 @@ tags:
21
25
  ports:
22
26
  - 8081
23
27
  order: 4
28
+ serviceOrder: 4
@@ -116,6 +116,16 @@ variables:
116
116
  header-includes:
117
117
  - |
118
118
  \usepackage{etoolbox}
119
+ \ifdefined\IfFontExistsTF
120
+ \IfFontExistsTF{Noto Sans Symbols 2}{%
121
+ \newfontfamily\textfallbackfont{Noto Sans Symbols 2}%
122
+ \newcommand{\textfallback}[1]{{\textfallbackfont #1}}%
123
+ }{%
124
+ \newcommand{\textfallback}[1]{#1}%
125
+ }
126
+ \else
127
+ \newcommand{\textfallback}[1]{#1}%
128
+ \fi
119
129
  \setlength{\tabcolsep}{3pt}
120
130
  \renewcommand{\arraystretch}{1.05}
121
131
  \AtBeginEnvironment{longtable}{\small}
@@ -6,11 +6,6 @@
6
6
  "apk": "fontconfig noto-fonts-emoji|noto-emoji perl chromium"
7
7
  }
8
8
  },
9
- "customizations": {
10
- "vscode": {
11
- "extensions": ["yzhang.markdown-all-in-one", "DavidAnson.vscode-markdownlint"]
12
- }
13
- },
14
9
  "remoteEnv": {
15
10
  "PUPPETEER_EXECUTABLE_PATH": "/usr/local/bin/chromium-no-sandbox",
16
11
  "PUPPETEER_SKIP_DOWNLOAD": "true"
@@ -15,5 +15,7 @@ tags:
15
15
  - markdown
16
16
  - docs
17
17
  - mermaid
18
+ imports:
19
+ - .shared/vscode/markdown-extensions.json
18
20
  ports: []
19
21
  order: 25
@@ -275,6 +275,16 @@ variables:
275
275
  header-includes:
276
276
  - |
277
277
  \usepackage{etoolbox}
278
+ \ifdefined\IfFontExistsTF
279
+ \IfFontExistsTF{Noto Sans Symbols 2}{%
280
+ \newfontfamily\textfallbackfont{Noto Sans Symbols 2}%
281
+ \newcommand{\textfallback}[1]{{\textfallbackfont #1}}%
282
+ }{%
283
+ \newcommand{\textfallback}[1]{#1}%
284
+ }
285
+ \else
286
+ \newcommand{\textfallback}[1]{#1}%
287
+ \fi
278
288
  \setlength{\tabcolsep}{3pt}
279
289
  \renewcommand{\arraystretch}{1.05}
280
290
  \AtBeginEnvironment{longtable}{\small}