From d39ff4ae8dad8db204a49430186e99ee0e87630f Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 13 Oct 2025 21:40:13 +0200 Subject: [PATCH] Improve workflow documentation --- .env | 7 +- README.md | 163 ++++++++++++++++++++++++++++++++++------------ build-and-push.sh | 5 ++ 3 files changed, 133 insertions(+), 42 deletions(-) diff --git a/.env b/.env index 727d57f..20b6909 100644 --- 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 \ No newline at end of file +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 \ No newline at end of file diff --git a/README.md b/README.md index 496e11e..49b48f2 100644 --- 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` diff --git a/build-and-push.sh b/build-and-push.sh index cb1b02c..0c8759e 100755 --- 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 \