Improve workflow documentation

2025-10-13 21:40:13 +02:00
parent eabab653a0
commit d39ff4ae8d
3 changed files with 133 additions and 42 deletions
--- a/.env
+++ b/.env
@@ -22,4 +22,9 @@ DEBUG=1
 LOCAL_IMAGE_NAME=spyder-conda
 SPYDER_IMAGE=git.maxboeer.com/schmax/spyder-desktop-docker:latest
 BUILDX_PLATFORMS=linux/amd64,linux/arm64
-BUILDX_BUILDER_NAME=spyder-buildx
+BUILDX_BUILDER_NAME=spyder-buildx
+# Optional: non-interactive registry login for build-and-push.sh
+# Do NOT commit secrets; prefer exporting these in your shell/session.
+# REGISTRY_HOST=git.maxboeer.com
+# REGISTRY_USER=your-username
+# REGISTRY_TOKEN=your-personal-access-token
--- a/README.md
+++ b/README.md
@@ -1,57 +1,138 @@
 # Spyder in Docker on Wayland

-This stack packages the Spyder IDE inside a Docker container and supports both native Wayland and optional X11 fallback sessions on Linux desktops.
+This stack packages the Spyder IDE inside a Docker container and supports both native Wayland and optional X11 fallback sessions on Linux desktops. Two workflows are available:

-## Quick Start (local build)
+- **Normal usage** – pull the published image `git.maxboeer.com/schmax/spyder-desktop-docker:latest` and run it with the runtime compose file.
+- **Development** – build the image locally, tweak dependencies, and (optionally) publish your own tag.

-1. Adjust the variables in `.env` to match your host (UID/GID, display socket paths, and bind mount locations).
-2. Ensure the bind mount folders exist (the repository includes `spyder-home/` and `spyder-workspace/` by default).
-3. Build and launch Spyder from source with the provided `compose.yaml`:
+## Normal Usage (recommended)

-```bash
-docker compose up
+1. **Install Docker** (Compose v2 included) on your Linux workstation.
+2. **Clone or download** this repository (or just grab `compose.runtime.yaml` and the `.env` example below).
+3. **Create a `.env` file** alongside `compose.runtime.yaml` and adapt the values to your system:
+
+	 ```
+	 UID=1000
+	 GID=1000
+	 HOST_USER=spyder
+	 HOST_GROUP=spyder
+	 SPYDER_HOME=/home/spyder
+	 SPYDER_WORKSPACE=/home/spyder/workspace
+	 SPYDER_HOME_VOLUME=./spyder-home
+	 SPYDER_WORKSPACE_VOLUME=./spyder-workspace
+	 XDG_RUNTIME_DIR=/run/user/1000
+	 WAYLAND_DISPLAY=wayland-1
+	 DISPLAY=:0
+	 SPYDER_IMAGE=git.maxboeer.com/schmax/spyder-desktop-docker:latest
+	 DEBUG=0
+	 ```
+
+	 Adjust `UID`, `GID`, `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`, and `DISPLAY` to match your desktop session.
+
+4. **Create the bind-mount folders** (only needed once):
+
+	 ```bash
+	 mkdir -p spyder-home spyder-workspace
+	 ```
+
+5. **Log in to the registry once** (required the first time you pull private images):
+
+	 ```bash
+	 docker login git.maxboeer.com
+	 ```
+
+	 Use your Gitea username and a personal access token with `read:packages` permission.
+
+6. **Launch Spyder** using the runtime compose file:
+
+	 ```bash
+	 docker compose -f compose.runtime.yaml up
+	 ```
+
+	 Spyder will open on your desktop. Stop it with `Ctrl+C` when done. For an X11 fallback, add `--profile x11` to the command.
+
+### Example `compose.runtime.yaml`
+
+```
+services:
+	spyder-wayland:
+		image: ${SPYDER_IMAGE}
+		environment:
+			UID: "${UID}"
+			GID: "${GID}"
+			HOST_USER: "${HOST_USER}"
+			HOST_GROUP: "${HOST_GROUP}"
+			SPYDER_HOME: "${SPYDER_HOME}"
+			SPYDER_WORKSPACE: "${SPYDER_WORKSPACE}"
+			HOME: "${SPYDER_HOME}"
+			WAYLAND_DISPLAY: "${WAYLAND_DISPLAY}"
+			XDG_RUNTIME_DIR: "${XDG_RUNTIME_DIR}"
+			QT_QPA_PLATFORM: "wayland"
+			QTWEBENGINE_DISABLE_SANDBOX: "1"
+			QTWEBENGINE_CHROMIUM_FLAGS: "--no-sandbox"
+			TZ: "Europe/Berlin"
+		volumes:
+			- ${SPYDER_HOME_VOLUME}:${SPYDER_HOME}
+			- ${SPYDER_WORKSPACE_VOLUME}:${SPYDER_WORKSPACE}
+			- ${XDG_RUNTIME_DIR}:${XDG_RUNTIME_DIR}
+		working_dir: ${SPYDER_WORKSPACE}
+		devices:
+			- "/dev/dri:/dev/dri"
+		shm_size: "1gb"
+		restart: "unless-stopped"
+
+	spyder-x11:
+		profiles:
+			- "x11"
+		image: ${SPYDER_IMAGE}
+		environment:
+			UID: "${UID}"
+			GID: "${GID}"
+			HOST_USER: "${HOST_USER}"
+			HOST_GROUP: "${HOST_GROUP}"
+			SPYDER_HOME: "${SPYDER_HOME}"
+			SPYDER_WORKSPACE: "${SPYDER_WORKSPACE}"
+			HOME: "${SPYDER_HOME}"
+			DISPLAY: "${DISPLAY}"
+			QT_QPA_PLATFORM: "xcb"
+			QT_X11_NO_MITSHM: "1"
+			QTWEBENGINE_DISABLE_SANDBOX: "1"
+			QTWEBENGINE_CHROMIUM_FLAGS: "--no-sandbox"
+			TZ: "Europe/Berlin"
+		volumes:
+			- ${SPYDER_HOME_VOLUME}:${SPYDER_HOME}
+			- ${SPYDER_WORKSPACE_VOLUME}:${SPYDER_WORKSPACE}
+			- /tmp/.X11-unix:/tmp/.X11-unix:ro
+		working_dir: ${SPYDER_WORKSPACE}
+		devices:
+			- "/dev/dri:/dev/dri"
+		shm_size: "1gb"
+		restart: "unless-stopped"
 ```

-Use the X11 fallback when necessary:
+## Development Workflow (build locally)

-```bash
-docker compose --profile x11 up
-```
+Use this path if you need to modify the Docker image or publish your own tag.

-Spyder exits when you close the IDE window. Stop the stack with `Ctrl+C`.
+1. Adjust `.env` to match your host (and optionally change `LOCAL_IMAGE_NAME`).
+2. Ensure `spyder-home/` and `spyder-workspace/` exist.
+3. Build and launch Spyder directly from the source tree:

-## Using a Prebuilt Image
+	 ```bash
+	 docker compose up
+	 ```

-Publish a multi-arch image to your Gitea container registry, then consumers can pull it directly.
+	 Add `--profile x11` for the X11 fallback.

-### 1. Configure registry access
+4. To publish your build to a registry:

-```bash
-docker login gitea.example.com
-```
+	 ```bash
+	 docker login git.maxboeer.com
+	 chmod +x build-and-push.sh
+	 ./build-and-push.sh
+	 ```

-Use your Gitea username and a personal access token with `write:packages` scope.
-
-### 2. Build and push
-
-`build-and-push.sh` wraps `docker buildx` to build Linux/amd64 and Linux/arm64 images and push them to the registry referenced by `SPYDER_IMAGE`.
-
-```bash
-chmod +x build-and-push.sh
-./build-and-push.sh
-```
-
-Adjust `SPYDER_IMAGE`, `BUILDX_PLATFORMS`, or `BUILDX_BUILDER_NAME` in `.env` to control the target registry, platforms, or builder instance.
-
-### 3. Let consumers run the image
-
-Distribute `compose.runtime.yaml` (or the example compose below). End users simply run:
-
-```bash
-docker compose -f compose.runtime.yaml up
-```
-
-Set `SPYDER_IMAGE` in their `.env` file if they host the image under a different name.
+	 The script uses Buildx to build `linux/amd64` and `linux/arm64` variants and pushes to the `SPYDER_IMAGE` declared in `.env`. You can enable non-interactive login by exporting `REGISTRY_HOST`, `REGISTRY_USER`, and `REGISTRY_TOKEN` before running the script.

 ## Environment Variables

@@ -65,7 +146,7 @@ Key settings live in `.env`:
 - `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`, `DISPLAY` – display/socket paths exported from the host session.
 - `DEBUG` – placeholder for future debug toggles.

-Update these values to relocate persisted data or point to non-standard display sockets.
+Update `.env` values to relocate persisted data or point to non-standard display sockets.

 ### Example `.env`

--- a/build-and-push.sh
+++ b/build-and-push.sh
@@ -44,6 +44,11 @@ else
  docker buildx use "$BUILDER"
 fi

+if [[ -n "${REGISTRY_HOST:-}" && -n "${REGISTRY_USER:-}" && -n "${REGISTRY_TOKEN:-}" ]]; then
+  echo "Logging in to $REGISTRY_HOST for non-interactive push"
+  echo "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" --username "$REGISTRY_USER" --password-stdin
+fi
+
 echo "Building multi-arch image for $SPYDER_IMAGE on platforms: $PLATFORMS"

 docker buildx build \