stremio-docker: a small Alpine image that puts the Stremio server and web player on one port

One image instead of three services

Stremio is described as a free application for streaming shows and movies. This repository exists to package it for Docker: the images bundle stremio-server, ffmpeg and the web player together in a small Alpine image, and the images are pushed to Dockerhub.

The motivation is in the README and it is specific rather than generic. The author built it to run Stremio on a Raspberry Pi 5 and could not find an image that had both the player and the server, while the official image seemed too big, lacked the web player, and did not work out of the box without HTTPS configured.

Three things are bundled, and each one exists for a reason. The server is the component that serves the catalogue and the streams. The web player is the browser interface that replaces the desktop application, which matters on a Pi or any device where you do not want to install a client. ffmpeg is the transcoder, and it is compiled rather than installed, which is the single most unusual thing in this repository and gets its own section below.

The audience is self-hosters rather than enterprises. The whole design assumes one person on a home network, a bind mount for state, and a handful of environment variables instead of a configuration file.

nginx collapses the server and the player onto port 8080

The networking design is the simplest and most useful part of the project. Both the web player and the streaming server run on port 8080 behind nginx, so only one port needs to be exposed.

That matters because the two components want different addresses. The web player is the thing a browser opens. The streaming server is what the player then talks to for actual media. The README describes the mechanism as automatic server configuration: the streaming server URL in the web player is derived from the URL of the browser that opened it, which is what the AUTO_SERVER_URL setting does.

# 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 that ships in the repository is short and sets the defaults the README recommends:

services:
  stremio:
    image: tsaridas/stremio-docker:latest
    restart: unless-stopped
    environment:
      NO_CORS: 1
      AUTO_SERVER_URL: 1
    ports:
      - "8080:8080"
    volumes:
      - "./stremio-data:/root/.stremio-server"

A mount for the server's home directory is present in the compose file and is the piece that makes the container worth running: the configuration files and the cache live on the host under ./stremio-data, so recreating the container does not lose your state.

The WEBUI_LOCATION setting extends the same idea. It sets the redirect page for the web player and sets up the streaming server when someone accesses port 11470 or 12470, with the default being the hosted shell at app.strem.io.

Everything is configured through environment variables

The README documents the configuration surface as a table of environment variables, each set with -e KEY="VALUE" in the docker run command.

The streaming server address has two knobs. AUTO_SERVER_URL, defaulting to 0, detects the streaming server URL from the browser's URL when set to 1, and the README calls that the recommended setting for most users. SERVER_URL sets the address by hand, for example http://192.168.1.10:11470/, and is what you use when the automatic detection guesses wrong.

HTTPS is driven by IPADDRESS. Set it to a valid IPv4 and the container generates and uses SSL certificates with the stremio domain. The README is unusually blunt about the limits of that: for public HTTPS it must be your real public IPv4 address, or 0-0-0-0 for auto-detect, and if the detected or provided address is not your real routable IPv4, certificate generation can fail. It will not work for IPv6. Custom domains and your own certificates are supported as well.

Two operational settings deserve attention. CASTING_DISABLED should be set to 1 if you are seeing SSDP errors in the logs, which is the usual symptom of discovery broadcasts that your network or container cannot handle. NO_CORS is listed with default 1 in the table while the compose file sets it explicitly, and the table describes it as the setting that enables the server's cors, so its polarity is worth confirming in your own deployment rather than assuming.

The remaining variables are operational: WEBUI_INTERNAL_PORT changes the port the web player listens on inside the container, defaulting to 8080, and FFMPEG_BIN and FFPROBE_BIN let you point at a custom binary path.

Running it as a single container instead of a compose stack

The compose file is the recommended route, but the README also gives the equivalent single-container form, and reading it side by side with the compose file makes the required settings obvious.

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 published port is 8080 on TCP, the volume maps the server's home directory to ./stremio-data on the host, and the restart policy brings the container back after a reboot. Once it is up, the web UI is available at http://<YOUR_SERVER_IP>:8080 and the streaming server is configured automatically from the URL of the browser used to open it.

Docker itself is the only requirement. On Linux the README suggests the usual convenience install and adding the user to the docker group, which needs a fresh login to take effect:

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

On Windows and macOS the answer is Docker Desktop, which has to be running before docker or docker compose will work.

One extra feature is listed in the feature list and belongs in the security discussion: HTTP Basic Auth, so the instance can be protected with a username and password.

ffmpeg is compiled from source, and the patches are architecture specific

The Dockerfile is the reason this repository exists rather than a one-line compose file, and it is where the real engineering sits.

The base is Alpine 3.24 across all target architectures, with Node coming from the Alpine package repositories. The ffmpeg stage then builds its own binary rather than installing the distribution package, and the Dockerfile states why in a comment: 4.X is the only version supported. The source is the jellyfin-ffmpeg fork, cloned at tag v4.4.1-4.

The build applies two patches from the repository's patches/ directory before configuring, one for mathops and binutils 2.41 and one for mlpdsp and armv5te with binutils 2.43. The configure step installs into /usr/lib/jellyfin-ffmpeg with the bindir set to /usr/bin, and the environment variable BIN is what the rest of the container refers to.

Hardware acceleration is handled in the same block. The libraries pulled in include libva-dev, and the case statement for armv6l, armv7l and armhf adds three flags, --disable-vaapi, --disable-hwaccel=h264_vaapi and --disable-hwaccel=hevc_vaapi, because those small ARM targets have no VAAPI device to talk to.

For VAAPI to work at all, the README is clear that the GPU has to be passed through to the container, and that this applies to Linux hosts. On Windows and macOS, transcoding uses the CPU only.

Where this image is the wrong choice

Three boundaries are structural rather than cosmetic.

The first is acceleration. The feature list and the requirements section both state that GPU and VAAPI passthrough is for Linux hosts, and that on Windows and macOS transcoding uses the CPU only, with an explicit warning not to rely on GPU acceleration inside the container on those platforms. A user on a Mac with an Apple Silicon chip who expects the same performance as a Linux box with a discrete GPU will be disappointed, and the image selected on macOS is the arm64 build, not an accelerated one.

The second is certificate generation. IPADDRESS has to be a real routable IPv4, auto-detection can fail, and IPv6 is not supported at all. On a home network with a changing address, or on an IPv6-only connection, automatic HTTPS is not going to work, and you need to bring your own domain and certificates.

The third is the cost of a custom base. The image carries a locally compiled ffmpeg and a set of local patches, which means the ffmpeg version is pinned to a fork branch rather than tracked by a distribution, and the image must be rebuilt when the project updates the patches. The maintainer absorbs that work; the operator inherits the consequence that the image is not simply the upstream binary in a smaller layer.

There is also the licensing reality of the ecosystem. This repository packages the official server and web player, which is why it can exist at all, and the add-on ecosystem around Stremio is a separate matter that this project neither controls nor documents.

MIT licence, regular tags, and a repository that keeps its own scripts

The licence is MIT, with a LICENSE file at the repository root, which is a permissive grant that suits a packaging project with no commercial restriction attached to the images.

The release record shows a steady cadence. v1.3.13 was published on 2026-10-13, v1.3.12 on 2026-10-06 and v1.3.11 on 2026-09-23. The last push was on 2026-10-13, the same day as the newest tag, so the tags and the branch are moving together rather than drifting apart.

The repository layout shows what else lives in it. There is a nginx/ directory for the proxy configuration, a patches/ directory holding the ffmpeg patches the build applies, and certificate.js and load_localStorage.js, which sit alongside localStorage.json and suggest that browser storage seeding is part of the setup. stremio-web-service-run.sh, restart_if_idle.sh and server-log-prefix.js are the runtime scripts, tests/ holds a test directory, and .devcontainer.json makes the repository itself developable inside a container.

The comparison the author draws is with the official image, and it is a fair one to hold this project to: smaller, includes the web player, and works without HTTPS already configured. Against a native install of the Stremio server on the host, the container wins on reproducibility and loses on the extra layer and the rebuild cost.

Editorial conclusion

stremio-docker fits a homelab operator on a Raspberry Pi or a small Linux box who wants the Stremio server and the web player reachable over one published port, with data in a bind-mounted directory and configuration done through environment variables. It does not fit a Windows or macOS user expecting GPU transcoding, an IPv6-only host, or anyone who wants the official image instead of a maintained fork with its own ffmpeg build. Verify first that the container starts with the compose file as shipped, that IPADDRESS matches your real routable IPv4 if you want automatic certificates, and that the volume mount lands on a path you intend to keep.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tsaridas/stremio-docker on GitHub