How to Set Up Sunshine Game Streaming on Linux with Docker Containers (2025)

If you're running a Linux server and want to stream games to multiple clients using Moonlight, Sunshine is the open-source game streaming host you've been looking for. Unlike proprietary solutions like NVIDIA GameStream, Sunshine gives you complete control over your streaming infrastructure and eliminates vendor lock-in.

This guide walks you through deploying Sunshine in Docker on Linux, configuring GPU acceleration, and connecting your first Moonlight client.

Why Docker for Sunshine on Linux?

Deploying Sunshine in a Docker container offers several advantages for Linux users:

• Isolation: Your game streaming service runs independently from your host system
• Easy updates: Pull the latest Sunshine image without system-wide changes
• Reproducibility: Same configuration across multiple machines
• Resource management: Limit CPU, memory, and GPU access per container
• Multiple instances: Run separate streaming sessions on different ports if needed

Linux distributions like Ubuntu, Fedora, and Debian have excellent Docker support, making containerization the cleanest deployment path for Sunshine.

Prerequisites

Before starting, ensure you have:

• Linux system with x86_64 CPU (Intel or AMD)
• Docker and Docker Compose installed
• NVIDIA GPU with CUDA support (recommended for 1080p/4K streaming) or AMD GPU with VAAPI
• 4GB+ RAM allocated to container
• Network access from your Moonlight client devices to your Linux host
• Port 47989 (TCP/UDP) and 48010 (TCP/UDP) open for streaming

Step 1: Install Docker and Docker Compose

First, install Docker on your Linux system. On Ubuntu/Debian:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

For other distributions, follow the official Docker documentation.

Verify installation:

docker --version
docker compose version

Step 2: Create Docker Compose Configuration

Create a docker-compose.yml file for Sunshine:

version: '3.8'

services:
  sunshine:
    image: lizardbyte/sunshine:latest
    container_name: sunshine-host
    restart: unless-stopped
    network_mode: host
    environment:
      - SUNSHINE_ENABLE_DOCKER_RUNTIME=1
      - SUNSHINE_LOG_LEVEL=info
    volumes:
      - ./sunshine/config:/home/sunshine/.config/sunshine
      - ./sunshine/logs:/home/sunshine/.local/share/sunshine/logs
    devices:
      - /dev/dri:/dev/dri  # GPU access for hardware encoding
      - /dev/snd:/dev/snd  # Audio device
    shm_size: 2gb  # Shared memory for encoding buffers

This configuration:

• Uses host networking for direct port access
• Mounts persistent config and logs directories
• Passes GPU and audio devices to the container
• Allocates 2GB shared memory for encoding operations

Step 3: Configure GPU Acceleration

For NVIDIA GPUs

If you have an NVIDIA GPU, ensure the NVIDIA Docker runtime is installed:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

Update your docker-compose.yml to specify NVIDIA runtime:

services:
  sunshine:
    image: lizardbyte/sunshine:latest
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    # ... rest of config

For AMD GPUs

AMD GPUs use VAAPI for hardware encoding. Install the necessary libraries:

sudo apt-get install libva-dev libva-vdpau-driver

Ensure the container has access to /dev/dri (included in the base compose file above).

Step 4: Start Sunshine Container

Launch Sunshine:

docker compose up -d

Verify it's running:

docker ps | grep sunshine

Check logs:

docker compose logs -f sunshine

You should see output indicating Sunshine is listening on ports 47989 and 48010.

Step 5: Access Sunshine Web UI

Open your browser and navigate to:

http://YOUR_LINUX_HOST_IP:47989

The first time you access the web UI, you'll configure:

• Application list: Add games and applications you want to stream
• Video settings: Resolution (1080p/1440p/2160p), bitrate, and frame rate
• Audio settings: Sample rate and channels
• Streaming codec: HEVC (H.265) for better compression or H.264 for broader compatibility

Step 6: Connect Moonlight Client

On your client device (Windows, macOS, Linux, or mobile), install Moonlight and:

1. Add your host using your Linux machine's IP address
2. Accept the certificate pairing request on the Sunshine web UI
3. Launch an application from the streamed list

Common Configuration Gotchas

Port Conflicts

If ports 47989 or 48010 are already in use:

ports:
  - "47989:47989/tcp"
  - "47989:47989/udp"
  - "48010:48010/tcp"
  - "48010:48010/udp"

Note: Changing ports requires corresponding Moonlight client configuration.

GPU Not Detected

Verify GPU access inside container:

docker exec sunshine-host nvidia-smi

For AMD:

docker exec sunshine-host vainfo

If the command fails, your device mapping isn't working. Check device permissions:

ls -la /dev/dri/
ls -la /dev/nvidia*

Audio Issues

Ensure PulseAudio or ALSA is properly configured inside the container. Add to your compose file:

environment:
  - PULSE_SERVER=unix:/run/user/1000/pulse/native
volumes:
  - /run/user/1000/pulse:/run/user/1000/pulse

Performance Tuning

For optimal streaming performance, adjust these Sunshine settings:

| Setting | Recommended Value | Notes | |---------|-------------------|-------| | Bitrate | 25-50 Mbps | Higher for 1440p/2160p | | Codec | HEVC | Better compression; requires client support | | Frame Rate | 60 FPS | Match your monitor refresh rate | | Resolution | 1080p | Increase if network bandwidth allows | | Key Frame Interval | 2 seconds | Lower for faster scene changes |

Monitoring and Maintenance

View real-time performance metrics:

docker stats sunshine-host

Update to the latest Sunshine version:

docker compose pull
docker compose up -d

Check logs for errors or warnings:

docker compose logs sunshine | grep -i error

Next Steps

Once your Sunshine Docker container is running:

1. Test network latency: Measure round-trip time between client and host using ping
2. Optimize bitrate: Start with 25 Mbps and adjust based on network conditions
3. Add multiple applications: Configure your favorite games in the Sunshine web UI
4. Set up remote access: Use a VPN or reverse proxy if accessing outside your local network
5. Monitor performance: Use the Moonlight statistics overlay to identify bottlenecks

Sunshine's Docker deployment on Linux provides a reliable, self-hosted alternative to proprietary game streaming services. The containerized approach ensures consistency across updates and makes managing your streaming infrastructure straightforward.