How do I get started with a hotio Docker image?

Updated

Pick your app from the hotio.dev container list, open that image's page, and copy the Docker CLI or Compose example it provides. Most hotio images ship with one of those two examples, so you can run the container without writing the configuration from scratch. If a step doesn't behave as expected, the documented fallback is the hotio Discord server.

What hotio.dev actually is

hotio.dev is the documentation site for the Docker images maintained by hotio. It is not an app store and it does not host the images for you — it tells you which images exist and how to run them. The site is organized into three groups:

Section What's in it
Containers → Base hotio/base, the shared foundation other images build on
Containers → Apps The individual applications, e.g. hotio/plex, hotio/sonarr, hotio/radarr, hotio/qbittorrent, hotio/jellyfin
Scripts Supporting tooling: SysInfo, Pullio, Arr, Discord Notifier

The Apps list is long and media-server oriented. Alongside the ones above you'll find hotio/bazarr, hotio/jackett, hotio/prowlarr, hotio/lidarr, hotio/whisparr, hotio/readarr-style companions, download clients like hotio/nzbget, hotio/sabnzbd and hotio/rflood, plus utilities such as hotio/tautulli, hotio/unpackerr, hotio/duplicacy, hotio/cloudflareddns, hotio/caddy, hotio/autoscan, hotio/doplarr, hotio/requestrr, hotio/seerr, hotio/slskd, hotio/stash, hotio/mergerfs, hotio/qbitmanage and hotio/qui. Check the live list before assuming a given app is covered — the set changes.

Step 1: Choose the image

Decide which application you want to run, then find its entry under Containers → Apps. The page name matches the image name, so hotio/sonarr lives on the Sonarr page.

If you're running several of these apps, note that they share hotio/base. That matters for how you organize volumes and networking, because the base image defines the common conventions the app images inherit.

Step 2: Read the example on that image's page

Open the page for your chosen image. Most images come with docker cli or compose examples — the site states this directly. Use whichever matches how you already manage containers:

  • Docker CLI — a single docker run command with the image tag, ports, volumes and environment variables filled in.
  • Docker Compose — a service block you paste into your compose.yaml and adjust.

Treat the example as the source of truth for that image. It already encodes the paths and variables the maintainer expects, which is the main reason to start from it rather than from a generic tutorial.

Step 3: Configure and run

Work through the example in this order, because each item changes what the next one needs:

  1. Image tag — the example shows a tag. Keep it as written unless you have a reason to pin differently.
  2. Volumes — the host paths in the example are placeholders. Point them at your real config and media directories. Getting these wrong is the most common reason a container starts but appears empty.
  3. Ports — map the container port to a free host port. If two of your hotio containers want the same host port, change one.
  4. Environment variables — set the values the example marks as required (user/group IDs, timezone, and any app-specific settings).
  5. Start it — run the CLI command, or docker compose up -d for the Compose version.

Expected result: the container starts, and the app's web UI is reachable at http://<host>:<port>.

Step 4: Verify

  • docker ps shows the container as running rather than restarting in a loop.
  • The app's web interface loads.
  • Your config directory on the host now contains files the app wrote — that confirms the volume mapping is correct.

If the container exits immediately, read its logs first; the error is usually a bad path or a missing variable from the example.

When you get stuck

The site's stated support channel is Discord: "If you've got any questions, feel free to join the discord server." That's the place to ask about a specific image, since the examples are maintained alongside the images themselves.

Two other things on the homepage are worth knowing so you don't go looking for them later: the site lists affiliate links and accepts donations (GitHub Sponsors, Open Collective, and Bitcoin). Neither affects how you use the images — they're just how the project is funded.

Quick checklist

  • [ ] Found the app under Containers → Apps
  • [ ] Opened that image's page and picked CLI or Compose
  • [ ] Replaced placeholder volume paths with real ones
  • [ ] Resolved any host port conflicts
  • [ ] Set required environment variables
  • [ ] Container running and web UI reachable
  • [ ] Joined Discord if something doesn't match the example