Invidious: interface, media paths and operational responsibility
Deploying Invidious: distinguish development Compose from the companion-based production stack
Prepare the documented three-service deployment, separate keys and persistent state, and verify more than a successful homepage before exposure.
What you will learn
- Select the correct composition before starting containers
- Configure the private connections and state deliberately
- Make acceptance and recovery explicit
Before you start
- Basic HTTP and container concepts
- Ability to distinguish application state from media traffic
Explain the dependency and trust boundaries, prepare a verifiable trial and interpret source/model evidence without overclaiming.
Key takeaways
- The repository-root Compose and the production guide are different artifacts.
- Use separate HMAC and companion keys, with matching companion endpoints.
- Accept a release through state and playback checks, not only a homepage.
Select the correct composition before starting containers
The root docker-compose.yml warns that it is for development and builds the local application source. Its two-service example is not the production recipe in the installation guide, which includes a Quay application image, a companion image and PostgreSQL. The guide also warns that playback will not work without companion configured in the development setup.
Begin with Docker Engine and Compose V2 in a controlled environment. Pin the source used for database initialization files and review the production recipe at the documentation revision cited below. The example uses mutable latest image tags; record and pin the image digests you actually validate for a repeatable release. A pinned article citation does not make a mutable container tag reproducible.
Configure the private connections and state deliberately
The application needs PostgreSQL settings, table initialization, a companion private_url, a companion key and an HMAC key. The documentation instructs operators to generate separate keys; the config reference requires the companion key to be exactly sixteen characters. The companion server secret must match that companion key, not the unrelated HMAC signing key. Replace example database credentials consistently on both sides.
Retain the database volume and the documented companion cache mount. Keep database and companion ports private unless a separately reviewed topology requires exposure. The simple recipe binds the frontend to 127.0.0.1:3000 for an edge reverse proxy. Configure domain, external_port and https_only to describe that edge; setting https_only is not a substitute for actually terminating TLS.
Make acceptance and recovery explicit
Validate the Compose syntax without printing resolved secrets, then start the reviewed stack in a non-production trial. Check database readiness, the application stats route, a known permitted video, preferences and a controlled account-state recovery. The stats endpoint is a service probe, not an end-to-end guarantee that companion, upstream access and browser playback all work.
Back up persistent data before changes and retain the previous application/companion digests. Treat database compatibility separately from an image rollback, and rehearse recovery instead of deleting volumes. The pinned guide supplies resource estimates, but those are not measurements of your workload. No Invidious installation, secret generation, database migration or playback test was performed for this article.
Implementation steps
- 1
Review the pinned installation guide and its production Compose.
- 2
Select verified image digests and private service connections.
- 3
Replace sample credentials and preserve the database/cache mounts.
- 4
Validate configuration, test a controlled deployment and rehearse restoration.
Copy-ready example
# Run only in your reviewed Invidious deployment directory.
# These inspect an existing configuration; they do not install or start it.
docker compose version
docker compose config --quiet
docker compose ps
curl --fail --max-time 10 http://127.0.0.1:3000/api/v1/statsFrequently asked questions
Can I clone the repository and treat its Compose as the production guide?
No. The root file explicitly targets development. The pinned installation documentation supplies the companion-based production composition.
Does a successful stats response prove playback?
No. It must be followed by an authorized end-to-end playback test and separate persistent-state checks.
Sources
- invidious/docker-compose.ymlSource checked 2026-09-08
- invidious/config/config.example.ymlSource checked 2026-09-08
- documentation/docs/installation.mdSource checked 2026-09-08