Installation

The easiest way to install Odeion is via the Docker image and Docker Compose v2. The wizard below will help you build a ‘docker-compose.yml’ file tailored to your setup and hardware.

1 Database

2 Storage

3 GPU

4 Media

5 Permissions

6 Proxy

7 Version

8 Config

Database

Choose how Odeion stores its data. The embedded option is simplest: Odeion manages PostgreSQL for you.

Embedded Zero setup. Odeion runs its own PostgreSQL instance inside the data directory.

PostgreSQL in Docker Compose Separate PostgreSQL container for easier backups, tuning, and upgrades.

External PostgreSQL Connect to an existing PostgreSQL 15+ server on your network.

Database password

Host Port

Database User

Password Require SSL

Storage

Host directory mounts give you direct access to your data for backups and best performance. Use fast storage (NVMe SSD) if available. Transcoding cache especially benefits from disk speed.

Data directory Thumbnails, subtitles, logs, backups, embedded database

Use host directory mount

Cache directory Transcode output, metadata images. Can be rebuilt if lost.

Use host directory mount

Hardware Transcoding

GPU acceleration dramatically reduces CPU usage during transcoding. If you're unsure, skip this and Odeion will fall back to software encoding.

None (CPU only) Software encoding. Works everywhere, but uses more CPU.

Intel / AMD (VAAPI) Passes through /dev/dri for hardware-accelerated encoding.

NVIDIA (NVENC) Requires the NVIDIA Container Toolkit.

Media Libraries

Add the directories where your media files are stored. These are mounted read-only into the container.

Name Host path ×

Name Host path ×

+ Add library

Permissions

Set the user and group ID the Odeion process runs as inside the container. This should match the owner of your media files so Odeion can read them without running as root.

Run id in your terminal to find your UID and GID.

PUID (User ID) PGID (Group ID)

Reverse Proxy

A reverse proxy with HTTPS is required for mobile and TV app connections. Caddy automatically obtains and renews TLS certificates via Let's Encrypt.

None No reverse proxy. Access Odeion directly on port 8080 over HTTP.

Caddy (automatic HTTPS) Adds a Caddy container that handles TLS certificates and proxies traffic to Odeion.

Domain name

Your domain's DNS must point to this server. Ports 80 and 443 must be open.

Version

Pick which release channel to track. You can change this later by editing the image: tag in your compose file.

Latest stable Tracks the :latest tag. Auto-updates to new stable releases when you docker compose pull.

Latest pinned Pins to the current newest stable release by version number. Won't auto-update — predictable upgrades.

Nightly Tracks the :nightly tag. Newest features, may be unstable.

Your docker-compose.yml

Copy

Save this as Caddyfile in the same directory as your docker-compose.yml:

Copy

Save the config above as docker-compose.yml, then run:

docker compose up -d

Visit http://your-server:8080 to begin the setup wizard.

Back Next

Next Steps

• Setup Wizard: first-run configuration walkthrough
• Reverse Proxy: required for mobile and TV app connections
• Configuration: environment variables and YAML settings management
• Transcoding: GPU hardware acceleration details