Installation

Odeion is distributed as a Docker image; Docker with Compose v2 is the only supported way to run it. Before you start, check the requirements and verify Docker is ready:

docker compose version

Build Your Compose File

The wizard below builds a docker-compose.yml tailored to your setup: database, storage paths, GPU passthrough, media libraries, and an optional Caddy reverse proxy. Your answers are saved in your browser, so you can leave and come back.

1 Database

2 Storage

3 GPU

4 Media

5 Permissions

6 Network

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.

Embedded mode sets DATABASE_URL: "local". The database lives inside the data directory volume, so it is covered by your data directory backups. Moving to an external PostgreSQL later requires a backup and restore, so pick external now if you already run one.

Database password

Pick something unique; this protects the PostgreSQL container on the internal compose network.

Host Port

Database User

Password Require SSL

Storage

Host directory mounts give you direct access to your data for backups and best performance.

Data directory Thumbnails, subtitles, logs, backups, embedded database. Persistent; back this up. Regular disks are fine here.

Use host directory mount

Cache directory Transcode output and metadata images. Can be wiped and rebuilt at any time. Put it on the fastest local disk you have (NVMe ideal); the transcode cache is capped at 32 GB by default.

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. You can re-run this wizard later.

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

Intel / AMD (VAAPI) Passes through /dev/dri for hardware-accelerated encoding. The device must exist on the host (check with ls /dev/dri); the container joins the render group automatically.

NVIDIA (NVENC) Requires the NVIDIA Container Toolkit on the host. Verify with docker info | grep -i nvidia before starting.

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)

Network

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 in this compose file. Access Odeion directly over HTTP, or put your own proxy in front (see the reverse proxy guide).

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

Host port Bind to localhost only (for an existing reverse proxy on this host)

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; upgrades are an explicit edit to your compose file.

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

Next steps

1. Save the YAML above as docker-compose.yml in an empty directory.
2. Save the Caddyfile next to it, and point your domain's DNS at this server.
3. Start the stack: docker compose up -dCopy
4. Watch it boot: docker compose logs -f odeionCopy
5. Visit http://your-server:8080 to begin the setup wizard.
6. Follow the setup wizard guide to create your admin account and first libraries.

Back Reset

Next

After the Wizard

The generated output ends with a step-by-step checklist: save the file, run docker compose up -d, and open the server URL to land in the first-run setup wizard. If anything fails to start, docker compose logs -f odeion shows what went wrong; the troubleshooting page covers the common cases.

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