Skip to main content

Introduction - Please Read!

Heads Up!

This project is the companion documentation for Home-Media-Docker. You will need to do the following in order to start working:

git clone https://github.com/Homemediadocker/Home-Media-Docker.git && cd Home-Media-Docker

You can read on to learn more about all the inner workings of this project.

In order to start using this package, you may need to make a few modifications for your usecase in the docker-compose.yml or in the associated included compose-files. Those two places ultimately drive the entire experience.

Also read this about Docker Compose and what you will need to be able to use it. This project uses docker compose V2.

The docker-compose.yml has a concept of includes: at the top level, which will dynamically include or parse the files based on the docker compose config that is used at runtime. For instance, in this project, it uses profiles so if you ran COMPOSE_PROFILES=traefik,jellyfin,sonarr,radarr docker compose config, it would only include those specific configuration yaml files in the final run. That's the most powerful part about profiles in docker, they are essentially like feature flags.

Impatient? Quick start here

Quick Start​

If you don't want to go through this whole doc site, you can quickly get started by running the following commands (once you pull the repo in).

Copy Env files​

  ./scripts/copyenv.sh

Spin up the containers​

  COMPOSE_PROFILES=all,jellyfin docker compose up -d
  • This will install everything for you plus a media server.

View Traefik Dashboard​

Get Stuck? Read the docs!​

  • See Docker Info for all the profiles if you only want a few services
  • See the Environment page for setting up your different env variables. You will probably encounter errors when spinning up containers if you just copied them without configuring anything. especially with the LOCAL_PATHs in the root .env, VPN setup, and the Authentik SSO Setup
    • Each container has its own .env file generated for you to configure individually and there is a global .env file to configure shared options.

Multiple Compose Files?​

This project has been refactored as of May 2024 to be more modular and have a different compose file for each service/use case. Everything is still run from the root level, but if you end up making changes to a compose file and I push an update to it, the blast radius is much smaller for conflict resolution.

Environment Variables​

Before you can run the startup script, you need to first setup your .env for docker to be able to fill in the variables in the docker container setup:

Default Location Variables for Local Paths

The default location variables for the local paths are defined as MacOS Volumes. Please change those to be where your local volumes are stored on your local machine.

For example, your setup may be a linux machine and your shares are stored in /media/MyShare/Movies or your stuff may be on a windows machine and your shares may be in %HOMEPATH%/Shares/Movies or something.

These are the default values:

## Local Paths
LOCAL_MOVIES_PATH="/Volumes/Movies" #CHANGE_ME
LOCAL_TV_PATH="/Volumes/Television" #CHANGE_ME
LOCAL_BOOKS_PATH="/Volumes/Books" #CHANGE_ME
LOCAL_DOWNLOADS_PATH="/Volumes/Downloads" #CHANGE_ME
LOCAL_BACKUPS_PATH="/Volumes/Backups" #CHANGE_ME

After you do that, you need to determine what VPN solution you will use.

VPN​

Out of the box, you get a lot of stuff pre-configured. It's very opinionated so you may need to modify things like the VPN setup, which currently uses the ghcr.io/bubuntux/nordvpn image. This is specifically for someone that may have a NordVPN setup.

IPVanish​

I highly recommend using Nord, but if you don't have a VPN currently and want another option to compare, IPVanish is also an option.

I have not tested this option, but here is an option utilizing IPVanish - see here.

IPVanish Docker Compose example (TLDR)
version: "3"
services:
  ipvanish:
    cap_add:
      - NET_ADMIN
      - NET_RAW
      - SYS_MODULE
    container_name: ipvanish
    devices:
      - /dev/net/tun
    environment:
      PASSWORD: YOUR_PASSWORD
      REGION: YOUR_REGION
      USERNAME: YOUR_USERNAME
      image: brettmcgin/private_internet_access
    ports:
      - <portsNeededByOtherService>
  busybox: # example service in the VPN network
    container_name: busybox
    image: busybox
    network_mode: service:ipvanish
    command: ifconfig | grep inet

Comment out the VPN block if you don't need it, or if you want to use your own solution.

If you decided to just use Nord, you can move forward.

Nord VPN Setup​

Important!

Token and subscription to NordVPN Is needed to use this. See here for configuring/retrieving your TOKEN.

Note that transmission's ports are configured to be used through the VPN. Simply remove the network_mode: service:vpn from the dockerfile and uncomment the ports if you remove the vpn connection from this dockerfile.

Note

You must explicitly configure the network_mode to pass the containers through the VPN connection (if required like for transmission), otherwise they are exposed on the Docker host and your public IP will be exposed!

Other setup​

Choose which media server you want to use (if any).

This script is setup with a few things in mind: Media Servers are heavy and absolutely not required to run this dockerized setup; but it is an all inclusive setup and specifically designed for someone to quickly scale and get started in an hour or less with an entire home media setup.

Emby​

This is a closed-source media server. It is free to use, but does have some pay walls. It is my go-to solution and it is a great solution for media management. It has a lot of stuff that Plex doesn't have, but also doesn't have a lot of ads (that Plex does have).

  • Freemium
  • Lots of support in forums
  • Server runs in any environment (Mac, Linux, Windows, Docker)
  • Works on every device type for clients

Plex​

This is another option, and one I used to use a lot. Plex offers a lot of simplicity and lots of support for anyone picking it up. It is also Free to use, but does have stuff behind paywalls that can be limiting. Emby does offer more for free than Plex does.

  • Freemium
  • Lots of support in forums
  • Server runs in any environment (Mac, Linux, Windows, Docker)
  • Works on every device type for clients (more than Emby)

Jellyfin​

This is 100% free and Open Source. Jellyfin is a hard fork of the Emby project before Emby went Closed-Source. Jellyfin is entirely community driven and developed and it offers everything that Emby offers but for free. There are a few things it does out of the box that are not quite what Emby has, and since it is OSS, it can have bugs that may not present the product as stable. However, Jellyfin looks and feels like Emby. Since the code is open, you can do a lot more customization with the setup and UI if you choose to (like adding your own logo or tweaking the entire CSS that comes with it).

The UI is similar, but yet very different from Emby, but lots of nods to the original project's direction and structure.

  • 100% Free forever
  • Lots of support in forums
  • Server runs in any environment (Mac, Linux, Windows, Docker)
  • Works on every device type for clients (the same as Emby)
  • Maybe not as stable since it is Open Source, but it has almost feature-for-feature what Emby has.

Running the Startup Script​

The Startup Script is not necessary to make this project work, but it does offer some simplicity when running it.

./scripts/startup.sh <mediaServer> ## media server optional

If you want everything including the media server.

./scripts/startup.sh jellyfin

## OR

COMPOSE_PROFILES=all,jellyfin docker compose up -d

Everything except a media server do this:

./script/startup.sh ## no media server will get created

## OR

docker compose up -d

If you choose not to use this and want to spin up each service individually, you can just do this:

docker compose up -d <serviceName> ## individual service will spin up

Where to start after your containers are live​

The first thing you should do after successfully spinning up your containers is go through all of the URLs found in the Home Media Containers section and figure out if your containers are accessible.

After that, if you have existing media then go to your media server and setup your Libraries.

If you don't have content, then setup Prowlarr first with all of your indexers. Then setup Sonarr (for TV) and Radarr (For Movies). You will need to obtain an API Key in each of those apps for Prowlarr to function the best. Once that is done, setup Transmission. I have Pushover setup to send me notifications, but most of them work with Discord or Slack as well.

You may want to do this in a different order, but that is how I did it. I do not want to walk you through it with screenshots. If you want to know more information then go to their respective sites for correct configuration of each one. Sonarr, Radarr, Prowlarr, and Transmission are the 4 main pieces of this setup that make it :chef-kiss: and completely automates all of the content gathering.