First working version

README.md

@@ -1,3 +1,136 @@
-# spyder-desktop-docker
+# Spyder in Docker on Wayland
 
-Dockerized Spyder IDE with native Wayland support, optional X11 fallback, GPU acceleration, and a ready-to-use Micromamba environment for reproducible Python development.
+This stack packages the Spyder IDE inside a Docker container and supports both native Wayland and optional X11 fallback sessions on Linux desktops.
+
+## Quick Start (local build)
+
+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`:
+
+```bash
+docker compose up
+```
+
+Use the X11 fallback when necessary:
+
+```bash
+docker compose --profile x11 up
+```
+
+Spyder exits when you close the IDE window. Stop the stack with `Ctrl+C`.
+
+## Using a Prebuilt Image
+
+Build the image locally, tag it, and push it to your registry of choice (example: `ghcr.io/your-account/spyder-wayland:latest`).
+
+```bash
+docker compose build
+docker tag spyder-conda ghcr.io/your-account/spyder-wayland:latest
+docker push ghcr.io/your-account/spyder-wayland:latest
+```
+
+Consumers can run the IDE without building locally using the provided `compose.runtime.yaml`:
+
+```bash
+docker compose -f compose.runtime.yaml up
+```
+
+Override the default image by exporting `SPYDER_IMAGE` in `.env`.
+
+## Environment Variables
+
+Key settings live in `.env`:
+
+- `UID`, `GID`, `HOST_USER`, `HOST_GROUP` – mirror the host user to preserve file ownership.
+- `SPYDER_HOME`, `SPYDER_WORKSPACE` – container paths for the Spyder home and project workspace.
+- `SPYDER_HOME_VOLUME`, `SPYDER_WORKSPACE_VOLUME` – host-side bind mounts for persistence (can be absolute or relative paths).
+- `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.
+
+### Example `.env`
+
+```
+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=ghcr.io/your-account/spyder-wayland:latest
+DEBUG=0
+```
+
+### Example `docker-compose.yml`
+
+```
+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"
+
+	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"
+```
+
+## GPU Acceleration
+
+The configuration keeps GPU acceleration enabled. The container shares `/dev/dri` with the host; if you run into driver issues, temporarily comment out the device mapping and set `QTWEBENGINE_CHROMIUM_FLAGS` or `QT_OPENGL` in `compose.yaml` to fall back to software rendering.
+
+## Notes
+
+- The entrypoint (`start-spyder.sh`) creates a user matching the host UID/GID at runtime and cleans up stale Spyder lock files before launching the IDE.
+- Python dependencies are managed via `micromamba` using `environment.yml`.
+- Shared memory is increased to 1 GB to satisfy QtWebEngine requirements.