Docker

This page runs Sovereign with plain docker run. Docker Compose and Kubernetes have pages of their own.

Running the Container

docker run --name sovereign \
  -v ./sovereign-data:/sovereign-data \
  -v /path/to/media:/media:ro \
  -p 5000:5000 \
  -e Sovereign__Authentication__Issuer=https://media.example.com/ \
  -e Sovereign__Network__TrustedProxyNetwork__0=172.16.0.0/12 \
  -e Sovereign__Authentication__AdminUsername=admin \
  -e Sovereign__Authentication__AdminPassword=Admin1! \
  -e Sovereign__DataSources__Radarr__0__Url=http://radarr:7878 \
  -e Sovereign__DataSources__Radarr__0__ApiKey=<radarr-api-key> \
  <sovereign-image>:<version>

<sovereign-image> stands for the Sovereign server image, and this page will say where to get it once the first one is published. Replace <version> with a release and pin it. There’s also a latest tag that follows the newest stable release (a prerelease never moves it), but a pinned version means an update only happens when you choose it. The image is built for x86-64 only.

Set the issuer to the HTTPS address your users will type. Sovereign doesn’t terminate TLS itself, so that’s the address of the reverse proxy in front of port 5000. Left at a localhost address, only a browser on the server’s own machine can sign in. See Authentication.

Then tell Sovereign where that proxy connects from, so it records each user’s real address rather than the proxy’s. 172.16.0.0/12 covers Docker’s default networks, which is right for a proxy in another container or on the same host. A proxy on another machine needs its own address instead; Trusted Proxy Networks explains how to find it.

The container runs as a non-root user (UID 1654) and creates its directories under /sovereign-data when it starts. On Linux, a host directory you bind-mount there has to be writable by that user, or the server exits at startup with an access-denied error. Create it and hand it over before the first run:

mkdir -p sovereign-data
sudo chown 1654:1654 sovereign-data

A named volume, as the Docker Compose page uses, needs no preparation.

The image sets its time zone to America/Chicago, which is what the server log’s timestamps use. Add -e TZ=<your-zone> to change it.

Injecting Secrets via env-file

Passing sensitive values as -e flags leaves them in your shell history. An env file keeps them out of it, and out of any compose file you commit, though anyone who can run docker inspect on the host can still read them.

Create a sovereign.env file:

Sovereign__Authentication__AdminUsername=admin
Sovereign__Authentication__AdminPassword=Admin1!
Sovereign__DataSources__Radarr__0__ApiKey=<radarr-api-key>
Sovereign__DataSources__Sonarr__0__ApiKey=<sonarr-api-key>

Pass it at runtime with --env-file:

docker run --name sovereign \
  -v ./sovereign-data:/sovereign-data \
  -v /path/to/media:/media:ro \
  -p 5000:5000 \
  --env-file sovereign.env \
  -e Sovereign__Authentication__Issuer=https://media.example.com/ \
  -e Sovereign__Network__TrustedProxyNetwork__0=172.16.0.0/12 \
  -e Sovereign__DataSources__Radarr__0__Url=http://radarr:7878 \
  -e Sovereign__DataSources__Sonarr__0__Url=http://sonarr:8989 \
  <sovereign-image>:<version>

You can still set non-sensitive values inline with -e alongside --env-file.

NFS Media Volumes

Docker’s --mount flag splits on commas, which conflicts with NFS mount options containing commas. Declare NFS-backed volumes as named volumes and create them before running the container:

docker volume create --driver local \
  --opt type=nfs \
  --opt device=:/MEDIA/movies \
  --opt "o=addr=192.168.1.10,nfsvers=4.1,ro,soft,timeo=100,retrans=2,rsize=1048576,wsize=1048576,nconnect=4,actimeo=60" \
  sovereign_media

docker run --name sovereign \
  -v ./sovereign-data:/sovereign-data \
  --mount type=volume,source=sovereign_media,target=/media/movies \
  -p 5000:5000 \
  --env-file sovereign.env \
  -e Sovereign__Authentication__Issuer=https://media.example.com/ \
  -e Sovereign__Network__TrustedProxyNetwork__0=172.16.0.0/12 \
  <sovereign-image>:<version>

The option string above is explained option by option on the NFS Media Storage page, along with why the mount should be read-only and fail fast.

Hardware Acceleration

See Hardware Acceleration for the docker run flags that expose a GPU device to the container.

Titles, artwork, people and descriptions shown in screenshots are fictional and were created for illustration. Sovereign doesn't include or supply any media: it plays the library you bring.