Config rejig WIP

README.md

@@ -12,7 +12,6 @@ Ansible config and a bunch of Docker containers.
 * Any number of Samba shares or NFS exports for you to store your stuff
 * A BitTorrent client
 * A Usenet downloader
-
 * Various media management tools - Sonarr, Sickchill, CouchPotato, Radarr, Bazarr, Lidarr
 * Media streaming via Plex or Emby
 * Music streaming with Airsonic
@@ -31,7 +30,7 @@ Ansible config and a bunch of Docker containers.
 * A dual panel local file manager
 * Self-service media request web application
 
-### Docker Containers Used
+### Available Applications
 
 * [Airsonic](https://airsonic.github.io/) - catalog and stream music
 * [Bazarr](https://github.com/morpheus65535/bazarr) - companion to Radarr and Sonarr for downloading subtitles
@@ -121,16 +120,17 @@ download code from the internet and trust that it's going to work as you expect.
 
     `cp -rfp inventories/sample inventories/my-ansible-nas`
 
-5. Review `group_vars/all.yml`. Change settings by overriding them in inventories/my-ansible-nas/group_vars/all.yml`.
+5. Review `group_vars/all.yml`. Change settings by overriding them in `inventories/my-ansible-nas/group_vars/all.yml`.
 
-6. If you plan to use Transmission with OpenVPN, update `inventories/my-ansible-nas/group_vars/vpn_credentials.yml`.
+6. Update `inventories/my-ansible-nas/inventory`.
 
-7. Update `inventories/my-ansible-nas/inventory`.
+7. Install the dependent roles: `ansible-galaxy install -r requirements.yml` (you might need `sudo` to install Ansible roles).
 
-8. Install the dependent roles: `ansible-galaxy install -r requirements.yml` (you might need `sudo` to install Ansible roles).
+8. Run the playbook - something like `ansible-playbook -i inventory nas.yml -b -K` should do you nicely.
 
-9. Run the playbook - something like `ansible-playbook -i inventory nas.yml -b -K` should do you nicely.
+## Upgrading
 
+**The way Ansible-NAS configuration is structured has changed!** See [Upgrading](https://davestephens.github.io/ansible-nas/upgrading/) for more information. See the **Getting Help** section if you get stuck.
 
 ## Documentation
 
@@ -167,7 +167,6 @@ Getting help is easy! You can:
 
 Contributions are always welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
 
-
 ## Support
 
 If you've enjoyed Ansible-NAS as much as I do working on it, please consider [buying me a coffee](https://ko-fi.com/davestephens) :coffee:

docs/upgrading.md

@@ -1,3 +1,28 @@
-# Upgrading
+# Upgrading Ansible-NAS
+
+## Upgrading from prior to January 2020 (`all.yml.dist` config style)
+
+If you're upgrading from [this](https://github.com/davestephens/ansible-nas/commit/52c7fef3aba08e30331931747c81fb7b3bfd359a) commit or earlier, these instructions are relevant to you.
+
+Rather than having to merge every new config line into your own `all.yml` file, now you only need to maintain the differences that are relevant to you in your own `all.yml`, stored within an inventory directory. Your inventory `all.yml` takes prescendence over `group_vars/all.yml`, which is how this setup works. `group_vars/all.yml` is now tracked as part of the repo.
+
+This will make updates from `master` much simpler, as there will be no requirement to merge changes from `all.yml.dist` into your own `all.yml` any more. You simply pull from master, then add the bits you're interested in into your inventory `all.yml`.
+
+Instructions to upgrade from prior to January 2020 ([this]([this](https://github.com/davestephens/ansible-nas/commit/52c7fef3aba08e30331931747c81fb7b3bfd359a)) commit or earlier):
+
+- Move your `group_vars/all.yml` somewhere safe.
+
+- Pull from master. There shouldn't be any merge conflicts unless you've been hacking on the project.
+
+- Create your own inventory and config files by copying `inventories/sample` to your own directory:
+
+    `cp -rfp inventories/sample inventories/my-ansible-nas`
+
+    Note that `my-ansible-nas` can be anything you want, but adjust the following instructions accordingly.
+
+- Then:
+
+    - **Quick and Dirty:** Copy the contents of your `all.yml` into `inventories/my-ansible-nas/all.yml`.
+
+    - **Nice and Tidy:** Copy only the differences between your own `all.yml` and the distribution `group_vars/all.yml` into `inventories/my-ansible-nas/all.yml`. This is likely to be things like `ansible_nas_hostname`, `samba_shares`, `ansible_nas_timezone`, enabled applications, any application tweaks you've made in config etc.
 
-Pull the latest Ansible-NAS repo, merge any new config sections from `group_vars/all.yml.dist` into your `group_vars/all.yml`, then run the playbook.

group_vars/all.yml

@@ -7,19 +7,13 @@
 ##     a n s i b l e - n a s      https://github.com/davestephens/ansible-nas
 
 ###
-### DO NOT CHANGE THE VARIABLES IN THIS FILE!
+### DO NOT EDIT THIS FILE!
 ### Add your customisations to inventories/<your_inventory>/group_vars/all.yml
 ###
 
-
+###
-# Set these options to true or false to toggle specific features
+### Ansible-NAS Applications
-
+###
-# External Access
-# Traefik will allow access to certain applications externally. To enable this you'll either; a domain name that points to your 
-# home static IP address, the cloudflare with the cloudflare_ddns dynamic DNS container enabled, or use a dynamic DNS provider like no-ip.
-# You'll also need to map ports 80 and 443 from your router to your ansible-nas server, then enable the per-app "available_externally"
-# settings.
-traefik_enabled: false
 
 # Downloading
 transmission_with_openvpn_enabled: false # Please see docs about how to set VPN credentials
@@ -100,6 +94,13 @@ ubooquity_enabled: false
 # Joomla
 joomla_enabled: false
 
+# External Access
+# Traefik will allow access to certain applications externally. To enable this you'll either; a domain name that points to your 
+# home static IP address, the cloudflare with the cloudflare_ddns dynamic DNS container enabled, or use a dynamic DNS provider like no-ip.
+# You'll also need to map ports 80 and 443 from your router to your ansible-nas server, then enable the per-app "available_externally"
+# settings.
+traefik_enabled: false
+
 ###
 ### General
 ###
@@ -284,9 +285,6 @@ cloudflare_email: "{{ ansible_nas_email }}"
 # Cloudflare 'Global API Key', can be found on the 'My Profile' page
 cloudflare_api_key: abcdeabcdeabcdeabcde1234512345
 
-##################################################################
-###### You shouldn't need to edit anything below this point ######
-##################################################################
 
 ###
 ### General
@@ -348,6 +346,14 @@ transmission_user_id: "0"
 transmission_group_id: "0"
 transmission_local_network: "192.168.1.0/24"
 
+# Transmission VPN Credentials
+# If you're using Transmission with a VPN, you'll need to set these credentials.
+# See https://hub.docker.com/r/dceschmidt/openvpn-client/ for supported VPN providers.
+openvpn_username: leisure-suit-larry
+openvpn_password: secretpassword
+openvpn_provider: AWESOMEVPNPROVIDER
+openvpn_config: United-Kingdom
+
 ###
 ### Joomla
 ###
@@ -364,7 +370,6 @@ pyload_download_directory: "{{ downloads_root }}"
 pyload_user_id: "0"
 pyload_group_id: "0"
 
-
 ###
 ### Plex
 ###