End of life — September 2026. SolarFlare is no longer maintained and this site is kept for reference only. No further releases, updates, bug fixes, or security patches will be published. Users are encouraged to migrate to Slipstream, the successor project, which remains actively maintained.

SolarFlareDocs
On this page
OperationsOps

Docker and containers

SolarFlare does not publish a container image. This page covers upstream Sunshine images and experimental compose.

6 min readUpdated September 2026

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#

ScenarioRecommendation
Quick upstream Sunshine smoke testUpstream image OK with caveats below
Production SolarFlare host on LinuxSource install — not Docker
Homelab media server with GPU passthroughCustom Dockerfile possible; expect manual tuning
Kubernetes / orchestrated gamingSee Games on Whales; not SolarFlare-maintained
CI compile-only buildsUse scripts/linux_build.sh Docker builder, not runtime image

Image tags#

Container tags combine a version channel and OS suffix. Bare tags such as latest, master, or vX.X.X are not complete image tags. Always use <SUNSHINE_VERSION>-<SUNSHINE_OS>, for example latest-ubuntu-24.04. Browse tags on Docker Hub and GHCR.

Runtime examples#

Tags combine version and OS suffix, for example latest-ubuntu-24.04. Internal Web UI port stays 47990.

yaml
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:/config

Ports, 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#

SymptomLikely causeMitigation
Black screen in MoonlightNo GPU in containerPass /dev/dri, validate host driver
Web UI unreachableWrong port mapMap host port to container 47990
Pairing lost on recreateEphemeral /configPersist volume mount
Encoder Function not implementedVA-API/NVENC not visibleDriver-matched image; check vainfo/nvidia-smi
Input not workingMissing uinput--device /dev/uinput, correct groups
High latency vs nativeNo fork tunables in upstream imageBuild SolarFlare from source on host
PreviousOperator GuidesNext Configuration Reference