Ansible Playbook to setup an automated Home Media Server stack running on Docker across a variety of platforms with support for GPUs, SSL, SSO, DDNS, and more.
Currently only Ubuntu 22.04+ is actively supported and is used for GitHub Actions testing.
RHEL based systems (CentOS 8, Fedora, Alma Linux, Rocky Linux) may work, but are no longer being tested against.
root
or sudo
access80/tcp
(HTTP) (Not required if using Cloudflare Tunnel)443/tcp
(HTTPS) (Not required if using Cloudflare Tunnel)32400/tcp
(Plex)This playbook assumes that it is a fresh install of an operating system that has not been configured yet. It should be safe to run on an existing system, BUT it may cause issues with Python since it installs Python 3.8, Docker repos, configures Nvidia GPU acceleration (if enabled), and configures network mounts (if enabled).
To ensure no conflicting changes with an existing system, you can run this playbook in "check mode" to see if any changes would be made by running make check
Setting up the individual container configurations, such as for Sonarr, Radarr, Overseerr, Prowlarr, etc. are outside the scope of this project. The purpose of this project is to ensure the necessary base containers are running with the appropriate configs.
It is recommended to read and follow this guide entirely as there is a lot of configuration options that are required to get the system up and running to its full potential.
Install requirements and clone the repository:
Ubuntu:
sudo apt update
sudo apt install git make python3-pip -y
sudo pip3 install ansible
# Clone the repository and then go into the folder
git clone https://github.com/ahembree/ansible-hms-docker.git
cd ansible-hms-docker/
Proceed to Configuration
To easily update from this git repo and update your custom variable names (due to deprecating/renaming variables), run:
make update
Previous variable names will still work for at least a year after the change and will be noted as such within the default configs. Please update to resolve.
Copy the base configurations to the vars/custom
directory by running:
make basic
You can also quickly copy the advanced configurations by running:
make advanced
NOTE: Re-running these commands will overwrite any existing files in the vars/custom
directory
If you wish to add a user(s) to the docker
group so they can run docker
commands without using sudo
, you can uncomment and modify the lines in vars/default/docker.yml
, or just run (as a user with sudo/root access) sudo usermod -aG docker <username>
By default, the content is laid out in the following directory structure, if you wish to change the install location, you must use the advanced configuration
Generated compose file location: /opt/hms-docker/docker-compose.yml
Container data directory: /opt/hms-docker/apps
Default mount path for local share (known as the mount_path
in this readme): /opt/hms-docker/media_data/
Media folder that contains movie and tv show folders (known as the media_path
in this readme): <mount_path>/_library
Movie folder: <media_path>/Movies
TV Show folder: <media_path>/TV_Shows
Secrets file (where sensitive key material is stored, other than the ansible variable files in vars/custom
): /opt/hms-docker/.env
This files default ownership and permissions requires you to enter the sudo/root password every time you run a docker-compose
command within the project directory
If you wish to get around this (and reduce security), you can change the secrets_env_user
, secrets_env_group
, and secrets_env_mode
within the advanced configuration files to the values you prefer, or...
These recommended values (if you wish to do this) will allow all users with docker
access to read the file, and thus run docker-compose
commands without needing to run as sudo/root, but will not allow them to modify.
secrets_env_user: root
secrets_env_group: docker
secrets_env_mode: 0640
All configuration options are in a (hopefully) aptly-named .yml
file. Once you copied the config you want (by running make basic
or make advanced
), these config files are now in vars/custom
Required settings to configure:
In vars/custom/plex.yml
plex_claim_token
: your Plex claim code from Plex's website
In vars/custom/main_custom.yml
hms_docker_domain
: the local domain name of the server to be used for proxy rules and (if supported) SSL certificates (e.g. home.local
)
hms_docker_media_share_type
: the type of network share (cifs
, nfs
, local
)
nfs
if using an NFS share/mountcifs
if using Samba or a Windows file sharelocal
if using a local directory on the same systemIn vars/custom/transmission.yml
transmission_vpn_provider
: the VPN provider (e.g. nordvpn
, see this page for the list of supported providers)
transmission_vpn_user
: the username of the VPN user
transmission_vpn_pass
: the password of the VPN user
Required settings for wildcard SSL certificate generation:
.com
or .net
, that Let's Encrypt is able to issue certificates for (see the Public Suffix List or the IANA Root Zone Database)vars/custom/traefik.yml
traefik_ssl_enabled
: whether or not to generate a wildcard SSL certificatetraefik_ssl_dns_provider_zone
: the zone of the DNS provider (e.g. example.com
, this will default to the hms_docker_domain
if not modified)traefik_ssl_dns_provider_code
: the "Provider Code" of the DNS provider (e.g. cloudflare
, found at link above)traefik_ssl_dns_provider_environment_vars
: the "Environment Variables", along with their values, of the DNS provider you're using (e.g. "CF_DNS_API_TOKEN": "<token>"
if using cloudflare
, found at link above)traefik_ssl_letsencrypt_email
: the email address to use for Let's Encrypttraefik_ssl_use_letsencrypt_staging_url
: whether or not to use the Let's Encrypt staging URL for initial testing (yes
or no
) (default: yes
)
no
to use the production server and get a valid certificate.If you have your media content stored on a NAS that will be connected via NFS or CIFS, please follow the directions in the NAS readme (after updating your hms_docker_media_share_type
to the correct value as outlined above)
You can run the playbook using the included Makefile
with the following commands:
# Check mode
make check
# Apply changes
make apply
Once the playbook has finished running, it may take up to a few minutes for the SSL certificate to be generated (if enabled).
If you do not already have a "wildcard" DNS record (*
) setup for the domain you used on your LOCAL DNS server (such as *.home.local
), create this A
record to point to the IP address of the server. If you enabled Cloudflare DDNS, an "overseerr" public A record will be created automatically.
You can also create individual A
records for each container listed in the container map, or have 1 A
record with multiple CNAME
records pointed to the A
record.
If the above DNS requirements are met, you can then access the containers by using the following URLs (substituting < domain >
for the domain you used).
You can also change the subdomain of each application within the advanced hms_docker_container_map
setting.
Plex: https://plex.< domain >
Sonarr: https://sonarr.< domain >
Radarr: https://radarr.< domain >
Bazarr: https://bazarr.< domain >
Overseerr: https://overseerr.< domain >
Requestrr: https://requestrr.< domain >
Prowlarr: https://prowlarr.< domain >
Transmission: https://transmission.< domain >
Tautulli: https://tautulli.< domain >
Traefik: https://traefik.< domain >
NZBGet: https://nzbget.< domain >
Authentik: https://authentik.< domain >
Tdarr: https://tdarr.< domain >
Homepage: https://homepage.< domain >
Uptime Kuma: https://uptime-kuma.< domain >