Introduction
Ister is a self-hosted media server in the spirit of Plex and Jellyfin. You point it at your media on disk, it scans and enriches everything with metadata, and the Ister player apps stream from it. This documentation set is for the person running the server — installing it, configuring it, and keeping it healthy. If you want to know how it works inside, the architecture documentation covers that.
What you are operating
An Ister deployment is a small set of services:
| Service | Required? | Role |
|---|---|---|
| Ister server | yes | The application itself: scanning, metadata, APIs, streaming |
| PostgreSQL | yes | The single source of truth for all data |
| RabbitMQ | yes | Message broker; all background work flows through it |
| OIDC provider | yes | Authentication — any Keycloak-compatible OpenID Connect provider |
| Typesense | optional | Full-text search across your libraries (chapter 05) |
Ister does not manage users itself: your OIDC provider (Keycloak, for example) does. The server validates the JWTs it issues.
What it can serve
- Movies and TV shows — metadata from TMDB, streamed as HLS with on-the-fly transcoding
- Music — metadata from MusicBrainz, cover art, artist images
- Books — epubs (read in the client, including EPUB 3 read-aloud books) and audiobooks, both attached to the same logical book; metadata from Open Library and Wikidata
- Comics — CBZ, PDF and epub, organised per series
- Podcasts — subscribed by RSS feed, refreshed hourly, episodes downloaded on demand
Deployment shapes
- Docker Compose — the repository ships
docker-compose.ymlas a reference stack (database, RabbitMQ, migrations, server). See Installation. - Kubernetes — the chart repository provides a Helm chart and runs a full end-to-end suite against it in CI.
- Multiple nodes — several servers can form one cluster, each owning its own disks; transcode work runs on the node that holds the file. See Multi-node.
The production artifact is a GraalVM native image: the published container image starts in a
fraction of a second and contains no JVM. You normally just pull ghcr.io/ister-app/server;
building it yourself is covered in Installation.
Chapter map
- Installation — images, migrations, first start, health endpoints
- Configuration — the full settings reference
- Libraries and media layout — how to organise files on disk
- Multi-node — running a cluster
- Search (Typesense) — enabling and maintaining full-text search
- Maintenance and troubleshooting — scheduled jobs, backup, monitoring
- Naming conventions — the exact directory and file naming rules per library type