Stremio Web supports three main installation paths depending on your use case.
Prerequisites Tool Required version Node.js 20.x (see .nvmrc) pnpm 10 or higher Docker Any recent version (Docker path only) Git Required by the Webpack build to read the commit hash
The Webpack config calls git rev-parse HEAD at build time to embed the commit hash in asset paths. A valid Git repository is required for all non-Docker build paths.
Installation methods Local development
Production build
Docker
Use this path when working on the codebase or exploring Stremio Web locally. 1. Clone and install git clone https://github.com/Stremio/stremio-web.git cd stremio-web pnpm install
2. Start the dev server This runs webpack serve --mode development on https://0.0.0.0:8080. The development server has the following characteristics:
HTTPS only (self-signed certificate)
Source maps via eval-source-map
DEBUG=true environment variable setService worker disabled
Live reload disabled — refresh the page manually after changes
3. Open the app Accept the browser’s certificate warning for localhost. Use this path to build a static bundle you can serve with any HTTP server. 1. Clone and install git clone https://github.com/Stremio/stremio-web.git cd stremio-web pnpm install
2. Build This runs webpack --mode production and outputs the bundle to the build/ directory. The production build includes:
Minified JS and CSS via Terser and cssnano
A Workbox-generated service worker for offline support
Assets hashed by commit SHA under build/<commit-hash>/
index.html at the root 3. Serve the build directory You can serve the build/ output with any static file server. The included http_server.js uses Express: The server listens on port 8080 and sets the following cache headers: Resource Cache-Control max-ageindex.html7,200 seconds (2 hours) All other assets 2,629,744 seconds (~30 days)
Long cache lifetimes on static assets are safe because asset filenames include the commit hash, so new deployments always fetch fresh files.
Use this path to run Stremio Web in a container without installing Node.js locally. 1. Build the image docker build -t stremio-web .
The Dockerfile uses a multi-stage build on node:20-alpine:
app stagepnpm i --frozen-lockfile and runs pnpm build.server stageFinal stage — copies only http_server.js, the built build/ directory, and the Express node_modules. No source code is included in the final image. 2. Run the container docker run -p 8080:8080 stremio-web
The container exposes port 8080 and starts http_server.js automatically. 3. Open the app Custom Node version The NODE_VERSION build argument controls the base image tag: docker build --build-arg NODE_VERSION=20-alpine -t stremio-web .
The app stage runs git rev-parse HEAD during the Webpack build. If you are building inside a Docker context that does not include the .git directory, the build will fail. Make sure your .dockerignore does not exclude .git.
Environment variables You can pass environment variables to the Webpack build to configure runtime behavior:
Variable Default Description SENTRY_DSNnullSentry DSN string. When set, Sentry error reporting is enabled. SERVICE_WORKER_DISABLEDfalseSet to true to skip service worker registration in production. DEBUGtrue in dev, false in prodEnables debug logging. VERSIONValue from package.json App version string embedded at build time. COMMIT_HASHOutput of git rev-parse HEAD Embedded automatically; used to namespace built assets.
Pass extra variables via the --env flag:
Next steps
Docker deployment Detailed guide to running Stremio Web with Docker in production
Self-hosting Serve Stremio Web behind a reverse proxy or on a custom domain
