Install Steps

Warning

This playbook assumes that it is a fresh install of an operating system that has not been configured yet.

To ensure no conflicting changes with an existing system, you can run this playbook in “check mode” (dry-run, preview, etc.) to see what, if any, changes would be made

Installation

1. Install Ansible for your system by following the instructions available here: https://docs.ansible.com/ansible/latest/installation_guide/installation_distros.html

2. Install requirements:

   sudo apt install git make python3-pip -y

3. Clone the repository:

   git clone https://github.com/ahembree/ansible-hms-docker.git

4. Go into the project folder:

   cd ansible-hms-docker/

5. Copy the default configuration files:

   make config

   Tip

   All configuration files are stored in inventory/group_vars/all

6. Optional If you will be installing to a remote host that is not the system you just cloned the repo to, see the Remote Host Install docs

---

Container Selection

To select the containers you want to use:

1. Modify the inventory/group_vars/all/container_map.yml file

2. Within there, you will find a giant list of the available containers and their config items

3. To enable a container, set its enabled value to true or yes

For an example of a container map entry and the description of what each setting does, check the Container List docs

Service Configuration

All configuration options are in a (hopefully) aptly-named .yml file.

Note

Any future containers variables will need to be added to your config file manually, if you chose to change them from the default values.

The default variable files are found in roles/hmsdocker/defaults/main/

Required Settings

General

1. Modify inventory/group_vars/all/main.yml to set the following variables

2. hms_docker_domain : the local domain name of the server to be used for proxy rules and (if enabled) SSL certificates (e.g. home.local)

3. hms_docker_media_share_type : the type of network share (cifs, nfs, local)

   • See the NAS setup page if using nfs or cifs
   • nfs if using an NFS share/mount
   • cifs if using Samba or a Windows file share
   • local if using a local drive/directory on the same system

4. hms_docker_mount_path : This is where the media and download folders will be “mounted” to the host. Recommended to change if using a network share and/or other drive in the system. This will mount to /data within the containers.

5. Plex If you have Plex enabled:

   • Modify inventory/group_vars/all/plex.yml and set:
   • plex_claim_token : your Plex claim code from Plex’s website

6. VPN Download Client If torrent download clients are enabled, see the Download Clients and VPNs documentation for the required variables

7. SSL/TLS Certificate If you want a SSL/TLS certificate for Traefik, see the SSL Certificates docs.

Running the playbook

You can run the playbook using the following commands:

# Run in "Check mode" to see changes before they are made
sudo make check

# Apply changes
sudo make apply

Debug mode

There is a debug_mode you can control from a variable in hms-docker.yml

Warning

Debug mode will also potentially output “secrets” (passwords, API keys) when enabled

Where Data is Stored

See the File Layout documentation for info on where data is stored.

Next Steps

Check out Configuring DNS on how to setup the DNS records on a (recommended) internal DNS server.

This will allow you to access the containers by going to https://<container>.<domain> in a browser and serve the SSL certificate, if enabled.

If you already have DNS enabled and want to get up and running quicker, check out the Automatic App Initialization.

If you are receiving a 404 or 5XX error when attempting to access the service, this is either because the container is not running, failing to start, or still starting. To troubleshoot, run docker logs -f <container name> and check the container logs.

Or, if you have Portainer enabled, you can also check the container logs there.