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.

Quick Start (local build)

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

docker compose up

Use the X11 fallback when necessary:

docker compose --profile x11 up

Spyder exits when you close the IDE window. Stop the stack with Ctrl+C.

Using a Prebuilt Image

Publish a multi-arch image to your Gitea container registry, then consumers can pull it directly.

1. Configure registry access

docker login gitea.example.com

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.

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:

docker compose -f compose.runtime.yaml up

Set SPYDER_IMAGE in their .env file if they host the image under a different name.

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 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
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.

4.9 KiB Raw Blame History Unescape Escape