Docker and containers
SolarFlare does not publish a container image. This page covers upstream Sunshine images and experimental compose.
Supported path#
Build SolarFlare on the host with ./scripts/linux-install.sh. Upstream lizardbyte/sunshine images do not include fork tunables, the SolarFlare Web UI, or API token features.
Caution
KMS capture, SCHED_RR pinning, and GPU governors often fail inside namespaces. Expect portal or X11 capture in containers.
When containers make sense#
| Scenario | Recommendation |
|---|---|
| Quick upstream Sunshine smoke test | Upstream image OK with caveats below |
| Production SolarFlare host on Linux | Source install — not Docker |
| Homelab media server with GPU passthrough | Custom Dockerfile possible; expect manual tuning |
| Kubernetes / orchestrated gaming | See Games on Whales; not SolarFlare-maintained |
| CI compile-only builds | Use scripts/linux_build.sh Docker builder, not runtime image |
Runtime examples#
Tags combine version and OS suffix, for example latest-ubuntu-24.04. Internal Web UI port stays 47990.
services:
sunshine:
image: lizardbyte/sunshine:latest-ubuntu-24.04
ipc: host
devices:
- /dev/dri/
ports:
- "47984-47990:47984-47990/tcp"
- "47998-48000:47998-48000/udp"
volumes:
- ./sunshine-config:/configPorts, volumes, and PUID/PGID#
Persist pairing certificates, sunshine.conf, and apps.json with -v /path/on/host/sunshine-config:/config (native installs use ~/.config/sunshine/). Required ports: TCP 47984–47990 plus 48010, UDP 47998–48000. Set PUID/PGID to match the host config owner; chown -R the volume if you change IDs after first run. amd64 and arm64 manifests exist per OS suffix, but SolarFlare release binaries are Linux x86-64 only.
Common failure modes#
| Symptom | Likely cause | Mitigation |
|---|---|---|
| Black screen in Moonlight | No GPU in container | Pass /dev/dri, validate host driver |
| Web UI unreachable | Wrong port map | Map host port to container 47990 |
| Pairing lost on recreate | Ephemeral /config | Persist volume mount |
| Encoder Function not implemented | VA-API/NVENC not visible | Driver-matched image; check vainfo/nvidia-smi |
| Input not working | Missing uinput | --device /dev/uinput, correct groups |
| High latency vs native | No fork tunables in upstream image | Build SolarFlare from source on host |