230 lines
7.2 KiB
Markdown
230 lines
7.2 KiB
Markdown
# 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. Two workflows are available:
|
||
|
||
- **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.
|
||
|
||
## Normal Usage (recommended)
|
||
|
||
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. **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: "no"
|
||
|
||
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: "no"
|
||
```
|
||
|
||
## Development Workflow (build locally)
|
||
|
||
Use this path if you need to modify the Docker image or publish your own tag.
|
||
|
||
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:
|
||
|
||
```bash
|
||
docker compose up
|
||
```
|
||
|
||
Add `--profile x11` for the X11 fallback.
|
||
|
||
4. To publish your build to a registry:
|
||
|
||
```bash
|
||
docker login git.maxboeer.com
|
||
chmod +x build-and-push.sh
|
||
./build-and-push.sh
|
||
```
|
||
|
||
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
|
||
|
||
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).
|
||
- `LOCAL_IMAGE_NAME` – tag applied to locally built images via `docker compose build`.
|
||
- `SPYDER_IMAGE`, `BUILDX_PLATFORMS`, `BUILDX_BUILDER_NAME` – registry target and buildx configuration used by `build-and-push.sh`.
|
||
- `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`, `DISPLAY` – display/socket paths exported from the host session.
|
||
- `DEBUG` – placeholder for future debug toggles.
|
||
|
||
Update `.env` 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
|
||
LOCAL_IMAGE_NAME=spyder-conda
|
||
SPYDER_IMAGE=gitea.example.com/max/spyder-wayland:latest
|
||
BUILDX_PLATFORMS=linux/amd64,linux/arm64
|
||
BUILDX_BUILDER_NAME=spyder-buildx
|
||
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.
|