diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 30b818abf..cbca09707 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -81,7 +81,6 @@ html http https IDEs -imagenet init intraworkshop IoT diff --git a/docs/examples/workshop-digits-cuda.yaml b/docs/examples/workshop-digits-cuda.yaml deleted file mode 100644 index 070fb691b..000000000 --- a/docs/examples/workshop-digits-cuda.yaml +++ /dev/null @@ -1,19 +0,0 @@ -name: digits-cuda -base: ubuntu@22.04 -sdks: - - name: tensorflow - plugs: - cuda: - interface: mount - workshop-target: /usr/local/cuda/lib64 - - name: imagenet - slots: - images: - interface: mount - workshop-source: $SDK/images - - name: cuda -connections: - - plug: tensorflow:cuda - slot: cuda:libs - - plug: tensorflow:images - slot: imagenet:images diff --git a/docs/examples/workshop-notebook.yaml b/docs/examples/workshop-notebook.yaml new file mode 100644 index 000000000..606671fc9 --- /dev/null +++ b/docs/examples/workshop-notebook.yaml @@ -0,0 +1,29 @@ +name: notebook +base: ubuntu@24.04 +sdks: + - name: ollama + channel: vulkan/stable + - name: uv + slots: + api: + interface: tunnel + endpoint: 8000 + - name: jupyter + - name: system + plugs: + jupyter: + interface: tunnel + endpoint: 127.0.0.1:8989 + app: + interface: tunnel + endpoint: 127.0.0.1:8090 + inference: + interface: tunnel + endpoint: 127.0.0.1:11434 +connections: + - plug: jupyter:venv + slot: uv:venv + - plug: system:app + slot: uv:api + - plug: system:inference + slot: ollama:ollama-server diff --git a/docs/explanation/workshops/concepts.rst b/docs/explanation/workshops/concepts.rst index 12b4e434a..55242f98b 100644 --- a/docs/explanation/workshops/concepts.rst +++ b/docs/explanation/workshops/concepts.rst @@ -329,43 +329,54 @@ eventually, all interface connections are in a single task *after* all the SDK layers have been created, because all components must be in place before the wiring can be done. -This example adds a slot, a plug, and a connection to its SDKs: +This example adds a slot, a plug, and two connections to its SDKs: .. code-block:: yaml :caption: .workshop/dev.yaml - :emphasize-lines: 5-8, 10-13, 15-17 + :emphasize-lines: 5-8, 11-14, 15-19 - base: ubuntu@22.04 name: dev + base: ubuntu@24.04 sdks: - - name: tensorflow - plugs: - cuda: - interface: mount - workshop-target: /usr/local/cuda/lib64 - - name: imagenet + - name: uv slots: - images: - interface: mount - workshop-source: $SDK/images - - name: cuda + api: + interface: tunnel + endpoint: 8000 + - name: jupyter + - name: system + plugs: + app: + interface: tunnel + endpoint: 127.0.0.1:8090 connections: - - plug: tensorflow:cuda - slot: cuda:libs + - plug: jupyter:venv + slot: uv:venv + - plug: system:app + slot: uv:api + +This extends the :samp:`uv` SDK +with a tunnel slot for a service its publisher never declared, +and the :samp:`system` SDK +with a tunnel plug that exposes that service on the host. -This extends the :samp:`tensorflow` SDK -with a standard path for CUDA runtime libraries. -In :samp:`connections`, -we explicitly connect the :samp:`cuda` plug, -newly defined under the :samp:`tensorflow` SDK, -to the :samp:`libs` slot from the :samp:`cuda` SDK. +The first entry in :samp:`connections` +wires a plug and a slot that the SDKs define themselves. Thus, upon workshop creation, -the plug will be connected +the :samp:`jupyter:venv` plug will be connected not to a default system SDK location on the host (for example, :file:`...///...`), -but to a library path *inside* the workshop, -which is set by :samp:`workshop-target`. +but to a directory *inside* the workshop, +which the :samp:`uv:venv` slot sets with :samp:`workshop-source`. + +The second entry connects the :samp:`app` plug, +newly defined under the :samp:`system` SDK, +to the :samp:`api` slot, +newly defined under the :samp:`uv` SDK. +It is needed because the two names differ: +on its own, |ws_markup| pairs a tunnel plug under the :samp:`system` SDK +only with a slot that carries the same name. Mind that the connection established in this way is no different from those created via the command line. diff --git a/docs/reference/definition-files/_interfaces/mount.rst b/docs/reference/definition-files/_interfaces/mount.rst index 7966569cc..4088d8907 100644 --- a/docs/reference/definition-files/_interfaces/mount.rst +++ b/docs/reference/definition-files/_interfaces/mount.rst @@ -27,6 +27,11 @@ A mount plug is described by these attributes: - Path inside the workshop used as the plug's target directory. Must be an absolute path; :envvar:`$SDK` expands to the SDK's installation path in the workshop. + |ws_markup| creates the directory if it is missing, + so the path must be writable. + An SDK's installation tree is mounted read-only, + so a target inside it resolves + only where the SDK already ships that directory. * - :samp:`mode` - integer @@ -79,3 +84,5 @@ A mount slot on a regular SDK is described by this attribute: - Path inside the workshop used as the slot's source directory. Must be an absolute path; :envvar:`$SDK` expands to the SDK's installation path in the workshop. + The directory must already exist when the connection is established; + unlike a plug's target, |ws_markup| does not create it. diff --git a/docs/reference/definition-files/workshop-definition.rst b/docs/reference/definition-files/workshop-definition.rst index 496e467a3..35867df2b 100644 --- a/docs/reference/definition-files/workshop-definition.rst +++ b/docs/reference/definition-files/workshop-definition.rst @@ -332,23 +332,35 @@ Workshop with an in-project SDK and a plug binding between SDKs: :language: yaml :caption: .workshop/go-dev.yaml -Workshop that grafts a plug and a slot onto its SDKs + +Workshop that grafts a slot and three plugs onto its SDKs and adds explicit connections; -besides using the fictional -:samp:`tensorflow`, :samp:`imagenet` and :samp:`cuda` SDKs, -it defines an additional slot under the :samp:`imagenet` SDK, -a plug under :samp:`tensorflow`, -and two connections: +besides using the :samp:`ollama`, :samp:`uv` and :samp:`jupyter` SDKs, +it defines an additional tunnel slot under the :samp:`uv` SDK, +three tunnel plugs under the :samp:`system` SDK, +and three connections: + +- One that connects the :samp:`jupyter:venv` plug + to the :samp:`uv:venv` slot, both provided by the SDKs themselves. + Without it, :samp:`jupyter:venv` falls back to :samp:`system:mount` + and Jupyter gets a private virtual environment on the host. + +- One that connects the newly defined :samp:`system:app` plug + to the newly defined :samp:`uv:api` slot. + +- One that connects the newly defined :samp:`system:inference` plug + to the preexisting :samp:`ollama:ollama-server` slot. -- One that connects the :samp:`tensorflow:images` plug - to the newly defined :samp:`imagenet:images` slot. -- Another that connects the :samp:`tensorflow:cuda` plug - to the preexisting :samp:`cuda:libs`. +The last two connections are required because the names differ: +a tunnel plug under the :samp:`system` SDK auto-connects +only to a slot that carries the same name. +The :samp:`system:jupyter` plug needs no entry for that reason, +pairing with the :samp:`jupyter:jupyter` slot on its own. -.. literalinclude:: ../../examples/workshop-digits-cuda.yaml +.. literalinclude:: ../../examples/workshop-notebook.yaml :language: yaml - :caption: .workshop/digits-cuda.yaml + :caption: .workshop/notebook.yaml Workshop that pulls an SDK from the try area: