mirror of
https://github.com/jimeh/ansible-adguardhome.git
synced 2026-02-18 22:56:39 +00:00
docs(readme): Write up basic readme and add license info
This commit is contained in:
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -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.
|
||||
119
README.md
119
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/)
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user