From 8e3fe78987120b402f90c00078c3f0a1239e5c4f Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Wed, 22 Jan 2020 01:02:22 +0000 Subject: [PATCH] docs(readme): Write up basic readme and add license info --- LICENSE | 21 ++++++++ README.md | 119 +++++++++++++++++++++++++++++++++------------- defaults/main.yml | 4 ++ 3 files changed, 110 insertions(+), 34 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..65a63a4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2020 Jim Myhrberg + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 011fba5..70cf7eb 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,99 @@ -Role Name -========= +# Ansible Role: AdGuard Home -A brief description of the role goes here. +Install [AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) privacy +protecting and ad-blocking DNS with Ansible. -Requirements ------------- +## Requirements -Any pre-requisites that may not be covered by Ansible itself or the role should -be mentioned here. For instance, if the role uses the EC2 module, it may be a -good idea to mention in this section that the boto package is required. +- Ansible >= 2.9 (might work on previous versions) -Role Variables --------------- +## Supported Operating Systems -A description of the settable variables for this role should go here, including -any variables that are in defaults/main.yml, vars/main.yml, and any variables -that can/should be set via parameters to the role. Any variables that are read -from other roles and/or the global scope (ie. hostvars, group vars, etc.) should -be mentioned here as well. +Tested on: -Dependencies ------------- +- Ubuntu 16.04 and 18.04 +- Debian stretch and buster +- EL 7 and 8 derived distributions -A list of other roles hosted on Galaxy should go here, plus any details in -regards to parameters that may need to be set for other roles, or variables that -are used from other roles. +It will likely work on other Debian and RHEL derived distros and versions than +what's listed above. -Example Playbook ----------------- +## Role Variables -Including an example of how to use your role (for instance, with variables -passed in as parameters) is always nice for users too: +Configurable role variables are all defined in `defaults/main.yml`: - - hosts: servers - roles: - - { role: ansible-adguardhome, x: 42 } +```yaml +# Version of AdGuard Home to install. If set to "latest", lookup the latest +# release via GitHub API. +adguardhome_version: "latest" -License -------- +# When desired version is "latest", use GITHUB_TOKEN environment variable when +# looking up the latest release via GitHub's API. If you get rate limit errors +# from GitHub's API, turni this on and set the GITHUB_TOKEN environment variable +# to a Personal Access Token with "repo" and "user" scopes. +adguardhome_use_github_token: false -BSD +# User to run AdGuard Home under. Must initially be "root" if no conig file is +# on disk. After going through the setup wizard, or manually adding a config +# file, this can be set to something else, like "adguard" for example. +adguardhome_user: root +adguardhome_group: "{{ adguardhome_user }}" -Author Information ------------------- +# When setting adguardhome_user to someething other than "root", this determines +# if the user will be created as a system user or not. Rule of thumb is if the +# user is logged in to by humans, it probably is not a system user. +adguardhome_system_user: true -An optional section for the role authors to include contact information, or a -website (HTML is not allowed). +# Default paths. +adguardhome_bin_dir: "/opt/{{ adguardhome_service_name }}/bin" +adguardhome_config_dir: "/opt/{{ adguardhome_service_name }}/config" +adguardhome_config_name: AdGuardHome.yml +adguardhome_data_dir: "/opt/{{ adguardhome_service_name }}" +adguardhome_tmp_dir: /tmp + +# Enable and start systemd service unit? +adguardhome_service_name: "adguardhome" +adguardhome_service_enable: true +adguardhome_service_start: true + +# Disable DNSStubResolver if systemd-resolved servicee is running. +adguardhome_disable_systemd_dnsstubresolver: true +``` + +## Example Playbook + +The following example will install the latest available release of AdGuard Home: + +```yaml +- hosts: all + roles: + - { role: jimeh.adguardhome } +``` + +If you did not already have a configuration file in place, AdGuard Home will now +be running with it's setup wizard on port `3000`. Once you've gone through the +setup wizard, the admin interface should be accessible on ports `80` and `443`. + +### Non-root User + +You can run AdGuard Home as a non-root user once you have a config file for in +place. Without a config file, it will simply refuse to start if not running as +`root`. + +If you don't already have a config file from a different install of AdGuard +Home, the best approach is: + +1. Run the role with `adguardhome_user` set to `root`. +2. Go through the setup wizard available on port `3000`. +3. Run the role again, this time setting `adguardhome_user` to a non-root + user. If the specified user does not exist, it will be created. + +Personally I run AdGuard Home under a user called `adguard`. + +## License + +This project is licensed under the MIT License. + +## Author Information + +[Jim Myhrberg](https://jimeh.me/) diff --git a/defaults/main.yml b/defaults/main.yml index 2a40846..70a6455 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -14,6 +14,10 @@ adguardhome_use_github_token: false # file, this can be set to something else, like "adguard" for example. adguardhome_user: root adguardhome_group: "{{ adguardhome_user }}" + +# When setting adguardhome_user to someething other than "root", this determines +# if the user will be created as a system user or not. Rule of thumb is if the +# user is logged in to by humans, it probably is not a system user. adguardhome_system_user: true # Default paths.