Skip to main content

​
Overview

Sunshine can be deployed as a Docker container using Docker Compose. This method provides isolation and easy management of the streaming service.
Docker images are not recommended for most users. Use native packages when possible for better performance and hardware access.

​
Prerequisites

  • Docker Engine 20.10 or later
  • Docker Compose v2 or later
  • GPU drivers installed on the host system
  • /dev/dri device access (for hardware encoding)

​
Available Images

Sunshine images are available on Docker Hub and GitHub Container Registry.

​
Image Tags

Combine version and OS to determine the tag: <VERSION>-<OS> Versions:
  • latest - Latest stable release
  • master - Latest development build
  • vX.X.X - Specific version
  • <commit-hash> - Specific commit
Operating Systems:
  • debian-bookworm
  • ubuntu-22.04
  • ubuntu-24.04
Example: lizardbyte/sunshine:latest-ubuntu-24.04

​
Supported Architectures

OSamd64/x86_64arm64/aarch64
debian-bookworm✅✅
ubuntu-22.04✅✅
ubuntu-24.04✅✅

​
Docker Compose Configuration

1
Step 1: Create docker-compose.yml
2
Create a docker-compose.yml file with the following contents:
3
docker-compose.yml
version: '3'
services:
  sunshine:
    image: lizardbyte/sunshine:latest-ubuntu-24.04
    container_name: sunshine
    restart: unless-stopped
    
    # GPU access for hardware encoding
    devices:
      - /dev/dri:/dev/dri
    
    # Required for proper IPC
    ipc: host
    
    # Volume mappings
    volumes:
      - ./config:/config
    
    # Environment variables
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    
    # Port mappings
    ports:
      - "47984-47990:47984-47990/tcp"  # Video, Audio, Control
      - "48010:48010"                   # Web UI (HTTPS)
      - "47998-48000:47998-48000/udp"  # Video, Audio
docker-compose.yml (Advanced)
version: '3'
services:
  sunshine:
    image: lizardbyte/sunshine:latest-ubuntu-24.04
    container_name: sunshine
    restart: unless-stopped
    
    # GPU access
    devices:
      - /dev/dri:/dev/dri
    
    # Network configuration
    network_mode: host
    
    # Required for proper IPC
    ipc: host
    
    # Volume mappings
    volumes:
      - ./config:/config
      - ./apps:/apps
      - ./logs:/var/log
    
    # Environment variables
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - SUNSHINE_USER=admin
      - SUNSHINE_PASS=changeme
    
    # Security options
    security_opt:
      - no-new-privileges:true
    
    # Resource limits
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M
4
Step 2: Configure Environment Variables
5
Replace the placeholder values with your settings:
6
VariableDescriptionExampleRequiredPUIDUser ID1000NoPGIDGroup ID1000NoTZTimezoneAmerica/New_YorkNoSUNSHINE_USERWeb UI usernameadminNoSUNSHINE_PASSWeb UI passwordchangemeNo
7
To find your user and group IDs, run: id $USER
8
Step 3: Create Configuration Directory
9
mkdir -p ./config
chown -R $(id -u):$(id -g) ./config
10
Step 4: Start the Container
11
docker-compose up -d
12
Step 5: Verify Deployment
13
# Check container status
docker-compose ps

# View logs
docker-compose logs -f sunshine

​
Volume Mappings

​
Configuration Directory

The /config directory stores all Sunshine configuration files: 
config/
├── sunshine.conf          # Main configuration
├── apps.json             # Application list
├── sunshine_state.json   # State and credentials
└── credentials/          # SSL certificates
    ├── cakey.pem
    └── cacert.pem

​
Optional Volumes

volumes:
  - ./logs:/var/log                    # Log files
  - ./games:/games:ro                  # Game directories (read-only)
  - /run/udev:/run/udev:ro            # Device information

​
Port Configuration

​
Required Ports

Port RangeProtocolPurpose
47984-47990TCPVideo/Audio streaming, Control
47998-48000UDPVideo/Audio data
48010TCPWeb UI (HTTPS)

​
Custom Port Configuration

To change the default port (47989), adjust all related ports: 
ports:
  - "48000-48006:47984-47990/tcp"
  - "48026:48010"
  - "48014-48016:47998-48000/udp"
environment:
  - SUNSHINE_PORT=48005

​
Network Modes

​
Bridge Mode (Default)

Uses Docker’s bridge network with explicit port mappings. Recommended for most deployments. 
ports:
  - "47984-47990:47984-47990/tcp"
  - "48010:48010"
  - "47998-48000:47998-48000/udp"

​
Host Mode

Uses the host’s network directly. Better performance but less isolation. 
network_mode: host
# Remove 'ports:' section when using host mode

​
Hardware Access

​
GPU Access (Required)

For hardware encoding, the container needs access to GPU devices: 
devices:
  - /dev/dri:/dev/dri              # Intel/AMD GPU
  - /dev/nvidia0:/dev/nvidia0      # NVIDIA GPU (optional)
  - /dev/nvidiactl:/dev/nvidiactl  # NVIDIA control (optional)

​
NVIDIA GPU (Additional Setup)

For NVIDIA GPUs, install NVIDIA Container Toolkit: 
services:
  sunshine:
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all

​
Using Podman

Sunshine works with Podman as a Docker alternative: 
podman run -d \
  --device /dev/dri/ \
  --name=sunshine \
  --restart=unless-stopped \
  --userns=keep-id \
  -e PUID=$(id -u) \
  -e PGID=$(id -g) \
  -e TZ=America/New_York \
  -v ./config:/config \
  -p 47984-47990:47984-47990/tcp \
  -p 48010:48010 \
  -p 47998-48000:47998-48000/udp \
  lizardbyte/sunshine:latest-ubuntu-24.04

​
Management Commands

​
Start/Stop Container

# Start
docker-compose up -d

# Stop
docker-compose down

# Restart
docker-compose restart

​
View Logs

# All logs
docker-compose logs

# Follow logs
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

​
Update Container

# Pull latest image
docker-compose pull

# Recreate container
docker-compose up -d

​
Access Container Shell

docker-compose exec sunshine bash

​
Building Custom Images

You can extend the Sunshine image for custom needs:
Dockerfile
ARG SUNSHINE_VERSION=latest
ARG SUNSHINE_OS=ubuntu-24.04
FROM lizardbyte/sunshine:${SUNSHINE_VERSION}-${SUNSHINE_OS}

# Install additional packages
RUN apt-get update && apt-get install -y \
    steam \
    && rm -rf /var/lib/apt/lists/*

# Custom entrypoint
ENTRYPOINT ["/usr/bin/sunshine"]
Build and use: 
docker build -t sunshine-custom .
Update docker-compose.yml: 
services:
  sunshine:
    image: sunshine-custom
    build: .

​
Troubleshooting

​
Container Won’t Start

# Check logs
docker-compose logs sunshine

# Verify GPU access
docker-compose exec sunshine ls -l /dev/dri

​
Permission Issues

# Fix config directory permissions
sudo chown -R $(id -u):$(id -g) ./config

​
Network Issues

# Verify ports are not in use
sudo netstat -tuln | grep -E '(47989|48010)'

# Try host network mode
# Add to docker-compose.yml:
network_mode: host

​
Performance Issues

  • Ensure /dev/dri device is accessible
  • Verify GPU drivers are installed on host
  • Use host network mode for better performance
  • Increase resource limits if needed

Build docs developers (and LLMs) love

Get started for freeTalk to us