docs for code-server

Author: FloSch62

docs/cmd/tools/code-server/start.md

@@ -0,0 +1,64 @@
+# code-server start
+
+## Description
+
+The `start` sub-command under the `tools code-server` command launches a dedicated [code-server](https://github.com/coder/code-server) container that is pre-configured with the VSCode Containerlab extension. The container exposes a VS Code compatible web UI in your browser and mounts both the host lab directory and user home so you can browse, edit, and run labs.
+
+On first start the command creates persistent directories under `~/.clab/code-server/<name>/` for configuration, extensions, and user data. It also seeds the extensions directory with the pre-baked extensions that ship in the container image and writes a default configuration (`password: clab`).
+
+## Usage
+
+```
+containerlab tools code-server start [flags]
+```
+
+## Flags
+
+### --image | -i
+
+Container image to use for the code-server instance. Defaults to `ghcr.io/kaelemc/clab-code-server:main`.
+
+### --name | -n
+
+Container name to create. Defaults to `clab-code-server`.
+
+### --labs-dir | -l
+
+Host directory that will be mounted inside the container at `/labs`. Defaults to `~/.clab` when not provided.
+
+### --port | -p
+
+Host TCP port that will be forwarded to the container's port `8080`. Defaults to `0`, which lets the container runtime pick a random available port.
+
+### --owner | -o
+
+Label value stored on the container to record the creator/owner. If omitted, Containerlab derives the value from `SUDO_USER` or `USER`.
+
+## Examples
+
+Start with default settings and let Docker assign a random host port:
+
+```bash
+❯ containerlab tools code-server start
+16:41:50 INFO Pulling image ghcr.io/kaelemc/clab-code-server:main...
+16:41:50 INFO Pulling image image=ghcr.io/kaelemc/clab-code-server:main
+main: Pulling from kaelemc/clab-code-server
+Digest: sha256:5d3b80127db6f74b556f1df1ad8c339f8bbd9694616e8325ea7e9b9fe6065fe9
+Status: Image is up to date for ghcr.io/kaelemc/clab-code-server:main
+16:41:50 INFO Done pulling image image=ghcr.io/kaelemc/clab-code-server:main
+16:41:50 INFO Creating code server container name=clab-code-server
+16:41:50 INFO Creating container name=clab-code-server
+16:41:50 INFO code-server container clab-code-server started successfully.
+16:41:50 INFO code-server available at: http://0.0.0.0:32779
+```
+
+Expose the service on a specific host port with a custom labs directory:
+
+```bash
+❯ containerlab tools code-server start --port 10080 --labs-dir /srv/containerlab/labs
+...[snip]...
+INFO code-server container clab-code-server started successfully.
+INFO code-server available at: http://0.0.0.0:10080
+```
+
+After the container starts you can browse to the reported URL and log in with username `clab` / password `clab`.

docs/cmd/tools/code-server/status.md

@@ -0,0 +1,48 @@
+# code-server status
+
+## Description
+
+The `status` sub-command under the `tools code-server` command inspects the active code-server containers that were launched via `containerlab`. It reports each container's runtime state, exposed port, mounted labs directory, and owner label so that you can quickly find connection details or verify cleanup.
+
+## Usage
+
+```
+containerlab tools code-server status [flags]
+```
+
+## Flags
+
+### --format | -f
+
+Output format for the listing. Accepts `table` (default) or `json`.
+
+## Examples
+
+List all running code-server containers in table form:
+
+```bash
+❯ containerlab tools code-server status
+╭──────────────────┬─────────┬───────┬──────────┬───────╮
+│ NAME             │ STATUS  │  PORT │ LABS DIR │ OWNER │
+├──────────────────┼─────────┼───────┼──────────┼───────┤
+│ clab-code-server │ running │ 32779 │ ~/.clab  │ clab  │
+╰──────────────────┴─────────┴───────┴──────────┴───────╯
+```
+
+Show the same information in JSON format (useful for scripting):
+
+```bash
+❯ containerlab tools code-server status --format json
+[
+  {
+    "name": "clab-code-server",
+    "state": "running",
+    "host": "",
+    "port": 32779,
+    "labs_dir": "~/.clab",
+    "owner": "clab"
+  }
+]
+```
+
+When no containers are active the command prints `No active code-server containers found` (or an empty JSON array when `--format json` is used).

docs/cmd/tools/code-server/stop.md

@@ -0,0 +1,39 @@
+# code-server stop
+
+## Description
+
+The `stop` sub-command under the `tools code-server` command removes a running code-server container. Use it to tear down the VS Code web terminal once you are done editing lab files. The command deletes the container but leaves the persistent configuration, extension, and user-data directories on disk so that the next start is nearly instant.
+
+## Usage
+
+```
+containerlab tools code-server stop [flags]
+```
+
+## Flags
+
+### --name | -n
+
+Name of the code-server container to remove. Defaults to `clab-code-server`.
+
+## Examples
+
+Stop the default helper container:
+
+```bash
+❯ containerlab tools code-server stop
+16:42:13 INFO Removing code-server container name=clab-code-server
+16:42:13 INFO Removed container name=clab-code-server
+16:42:13 INFO code server container removed name=clab-code-server
+```
+
+Target a specific container name:
+
+```bash
+❯ containerlab tools code-server stop --name dev-code-server
+16:45:01 INFO Removing code-server container name=dev-code-server
+16:45:01 INFO Removed container name=dev-code-server
+16:45:01 INFO code server container removed name=dev-code-server
+```
+
+If the named container is not found the command returns an error from the underlying runtime (for example `container "dev-code-server" not found`).

mkdocs.yml

@@ -119,6 +119,10 @@ nav:
               - start: cmd/tools/api-server/start.md
               - stop: cmd/tools/api-server/stop.md
               - status: cmd/tools/api-server/status.md
+          - code-server:
+              - start: cmd/tools/code-server/start.md
+              - stop: cmd/tools/code-server/stop.md
+              - status: cmd/tools/code-server/status.md
           - sshx:
               - attach: cmd/tools/sshx/attach.md
               - detach: cmd/tools/sshx/detach.md