tsaridas/stremio-docker repository overview

⁠Easy stremio on Docker

⁠Introduction

Stremio⁠ is a free application which lets you stream your favorite shows and movies.

The Docker images in this repository bundle stremio-server, ffmpeg and web player for you, ready to use in a small Alpine image.

I built this to run Stremio on my Raspberry Pi 5 and couldn't find something that has both player and server but also the official image seemed too big but also lacks the Web Player and doesn't work out of the box if no HTTPS is configured.

⁠Features

• All-in-One: Bundles Stremio server, web player, and ffmpeg in a single container.
• Simple Networking: Both the web player and server run on port 8080 behind nginx, so you only need to expose one port.
• Automatic Server Configuration: Use AUTO_SERVER_URL or SERVER_URL to automatically configure the streaming server URL in the web player.
• HTTPS Out-of-the-Box: Automatically generates and uses SSL certificates when an IPADDRESS is provided.
• Custom Certificates: Supports using your own domain and SSL certificates.
• Hardware Acceleration (Linux hosts): Includes ffmpeg with VAAPI support for Intel and AMD GPUs when you pass through the GPU on Linux (see FFMPEG⁠).
• Cross-Platform: Builds are available for amd64, arm/v6, arm/v7, arm64/v8, and ppc64le.
• Runs on Linux, Windows, and macOS: Use Docker Engine on Linux or Docker Desktop⁠ on Windows and macOS—the same docker / docker compose commands apply. On macOS, Docker pulls the matching image for your Mac: Intel (linux/amd64) or Apple Silicon (M series) (linux/arm64).
• Transcoding on Windows and macOS: When you run this container on Windows or macOS, transcoding uses the CPU only. GPU/VAAPI passthrough (see FFMPEG⁠) is for Linux hosts.
• HTTP Basic Auth: Secure your instance with a username and password.

⁠Requirements

• Docker on your machine. The container runs on Linux (Docker Engine or similar), Windows, and macOS (typically via Docker Desktop⁠). On macOS, Intel Macs use the amd64 image and Apple Silicon (M series) use the arm64 image; Docker Desktop selects the correct architecture automatically.
• Expect CPU transcoding on Windows and macOS—do not rely on GPU acceleration inside the container on those platforms.

⁠Installation

⁠1. Install Docker

• Linux: If you haven't installed Docker yet, you can usually install it with:

curl -sSL https://get.docker.com | sh
sudo usermod -aG docker $(whoami)
exit

And log in again.

• Windows and macOS: Install Docker Desktop⁠ and ensure it is running before you use docker or docker compose.

⁠2. Run Stremio

Option A: Using Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/tsaridas/stremio-docker.git
cd stremio-docker

# Edit compose.yaml if needed, then run:
docker compose up -d

The compose file includes common settings like NO_CORS: 1 and AUTO_SERVER_URL: 1.

Option B: Using Docker Run

docker run -d \
  --name=stremio-docker \
  -e NO_CORS=1 \
  -e AUTO_SERVER_URL=1 \
  -v ./stremio-data:/root/.stremio-server \
  -p 8080:8080/tcp \
  --restart unless-stopped \
  tsaridas/stremio-docker:latest

The Web UI will now be available on http://<YOUR_SERVER_IP>:8080. The streaming server will be auto-configured for you from the URL of the browser you are using to open it.

⁠Configuration Options

These options can be configured by setting environment variables using -e KEY="VALUE" in the docker run command.

There are multiple other options defined but probably best not setting any.

⁠Usage Scenarios

Here are some common ways to configure and use this Docker image.

⁠Scenario 1: Simple HTTP (No Certificate)

This is the easiest option and works on your local network without needing a public IP or DNS.

• Do not set the IPADDRESS environment variable.
• Set NO_CORS=1 to allow the web player to connect to the server.
• Set AUTO_SERVER_URL=1 to automatically set the server URL.

docker run -d \
  --name=stremio-docker \
  -e NO_CORS=1 \
  -e AUTO_SERVER_URL=1 \
  -p 8080:8080 \
  tsaridas/stremio-docker:latest

Access Stremio at http://<YOUR_LAN_IP>:8080.

⁠Scenario 2: HTTPS with Public IP

This option automatically gets a certificate for a *.stremio.rocks subdomain and points it to your public IP address.

• Set IPADDRESS=0.0.0.0 to auto-detect your public IP.
• Expose port 8080 and configure port forwarding on your router.

docker run -d \
  --name=stremio-docker \
  -e IPADDRESS=0.0.0.0 \
  -e AUTO_SERVER_URL=1 \
  -p 8080:8080 \
  tsaridas/stremio-docker:latest

The container will generate a certificate and an A record for your public IP. To find the FQDN, look for a .pem file in your mounted volume (~/.stremio-server).

⁠Scenario 3: HTTPS with Private IP

This is useful for accessing Stremio via HTTPS on your local network. It generates a certificate for a *.stremio.rocks subdomain that resolves to your private IP.

1. Set IPADDRESS to your server's private LAN IP (e.g., 192.168.1.10).

2. The container will generate a certificate for a domain like 192-168-1-10.519b6502d940.stremio.rocks. Find the exact FQDN from the .pem filename in your mounted volume.

3. Add an entry to your hosts file on your client machine to point the FQDN to your server's private IP.

   • Linux/macOS: /etc/hosts
   • Windows: c:\Windows\System32\Drivers\etc\hosts

   192.168.1.10    192-168-1-10.519b6502d940.stremio.rocks
   

   Copy

4. Run the container:

   docker run -d \
     --name=stremio-docker \
     -e IPADDRESS=192.168.1.10 \
     -e AUTO_SERVER_URL=1 \
     -p 8080:8080 \
     -v ./stremio-data:/root/.stremio-server \
     tsaridas/stremio-docker:latest
   

   Copy

5. Access Stremio at https://192-168-1-10.519b6502d940.stremio.rocks:8080.

⁠Scenario 4: HTTPS with Your Own Domain and Certificate

If you have your own domain and SSL certificate, you can use them directly.

• Place your certificate file (e.g., certificate.pem) in the directory you mount to /root/.stremio-server.
• Set the DOMAIN and CERT_FILE environment variables.

docker run -d \
  --name=stremio-docker \
  -e DOMAIN=your.custom.domain \
  -e CERT_FILE=certificate.pem \
  -e AUTO_SERVER_URL=1 \
  -v ./stremio-data:/root/.stremio-server \
  -p 8080:8080 \
  tsaridas/stremio-docker:latest

The WebPlayer will be available at https://your.custom.domain:8080.

⁠Updating

To update to the latest version, simply run:

docker stop stremio-docker
docker rm stremio-docker
docker pull tsaridas/stremio-docker:latest

And then run your docker run or docker compose up -d command again.

⁠Advanced Topics

⁠FFMPEG

We build our own ffmpeg from the jellyfin repo (version 4.4.1-4), which includes:

• Hardware acceleration support for both Intel and AMD (VAAPI)
• Multiple codec support (H.264, HEVC, VP9, etc.)
• Optimized for streaming workloads

On Linux, hardware acceleration is used when the GPU is available to the container. To enable it, you must expose your GPU device to the container.

Windows and macOS

Docker Desktop on Windows and macOS does not expose Linux VAAPI devices the way this image expects. Transcoding runs on the CPU; plan for higher CPU use than on a Linux host with GPU passthrough.

Support for Intel/AMD GPU Transcoding (VAAPI) — Linux only

If you have a supported Intel or AMD GPU on Linux, you can enable hardware transcoding by passing the dri device to the container:

Docker Compose:

services:
  stremio:
    # ... your other config
    devices:
      - "/dev/dri:/dev/dri"

Docker CLI:

docker run -d \
  # ... your other flags
  --device /dev/dri:/dev/dri \
  tsaridas/stremio-docker:latest

⁠Builds

Builds are created for the following architectures:

• linux/amd64
• linux/arm/v6
• linux/arm/v7
• linux/arm64/v8
• linux/ppc64le

Images are automatically built and tested on pull requests using GitHub Actions.

Build tags:

• latest: Builds when a new version of the server or Web Player is released.
• nightly: Builds daily from the development branch of the web player.
• vX.X.X: Specific release versions.

Images are hosted on Docker Hub⁠.

⁠Customizing Local Storage

Stremio's web app stores settings in the browser's local storage. You can pre-configure these settings by editing the localStorage.json file and mounting it into the container:

docker run -d \
  # ... your other flags
  -v /path/to/your/localStorage.json:/srv/stremio-server/build/localStorage.json \
  tsaridas/stremio-docker:latest

⁠Shell

The old Stremio shell files are available at http(s)://<your_url>/shell/. These may have issues with some content like YouTube videos.

⁠Known issues

• Unable to login through Facebook.

⁠Suggestions

⁠DNS Caching

Stremio can be heavy on DNS queries. It's recommended to use a local DNS cache like dnsmasq to improve performance.

⁠Idle Restart

The restart_if_idle.sh script can restart the Stremio server when it's not in use. You can add this as a healthcheck in your compose.yaml:

  healthcheck:
    test: ["CMD-SHELL", "./restart_if_idle.sh"]
    interval: 1h
    start_period: 1h
    retries: 1

⁠Security

• HTTP Basic Authentication: Supported via USERNAME and PASSWORD environment variables.
• HTTPS: Automatic certificate generation is enabled when IPADDRESS is set.
• CORS: Can be disabled for local deployments with NO_CORS=1.
• Minimal Images: All images are built on Alpine with minimal dependencies.

⁠ToDo

• Build another image with a base that is small and has glibc.
• Automatically add addons passed from environmental variables.
• Add nginx CORS for security.

PRs and Issues are welcome. If you find an issue, please let me know.