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 06) |
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
On top of the media itself, users get a personal layer: playlists (hand-built or smart, filter-based), saved views with custom filters, per-user ratings and playback history, registered devices with remote control and playback handoff, listen-along with another user's session, and automatic intro/outro detection with a skip button. None of it needs operator setup; the model is described in Personal library and devices.
Deployment shapes
- Docker Compose — the repository ships
docker-compose.ymlas a reference stack (database, RabbitMQ, a development Keycloak, migrations, server). The Quick start walks you through it; Installation covers keeping it. - 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. A node can also be transcode-only, owning no media and encoding for another node's disks. 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
- Quick start — a running, signed-in server with test media in about ten minutes
- Installation — prerequisites, 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
- Users, sharing, and access — admins, per-library visibility, playback-session sharing