From ec75520bd4968d1c4f1bd362eeb4cf8abe8524fd Mon Sep 17 00:00:00 2001 From: Laur Ivan Date: Fri, 23 Sep 2022 12:50:15 +0200 Subject: [PATCH] Add documentation. Better configuration. Expose DB port. --- README.md | 137 ++++++++++++++++++++++++++------ defaults/main.yml | 11 ++- tasks/main.yml | 1 + templates/docker-compose.yml.j2 | 10 ++- templates/env.db.conf.j2 | 4 + templates/env.plausible.conf.j2 | 4 +- 6 files changed, 136 insertions(+), 31 deletions(-) create mode 100644 templates/env.db.conf.j2 diff --git a/README.md b/README.md index 225dd44..9f38fe2 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,127 @@ -Role Name -========= +# laurivan.plausible -A brief description of the role goes here. +THis is a role to install [Plausible](https://plausible.io/) via Docker. -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. +You need a machine with Docker installed. -Role Variables --------------- +## Role Variables -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. +Plausible depends on several components (SMTP, Clickhouse, PostgreSQL) and this role is designed to install them as a package. All variables are listed below (see also `defaults/main.yml`). -Dependencies ------------- +# Plausible parameters -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. +`plausible_port` defined the exposed port for the web site (including JS delivery and API): -Example Playbook ----------------- +```yaml +plausible_port: 8000 +``` +You need an admin user to be able to access the site: -Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: +```yaml +plausible_admin_user_email: changeme@example.com +plausible_admin_user_name: change-me +plausible_admin_user_pwd: change-me +``` - - hosts: servers - roles: - - { role: username.rolename, x: 42 } +The hosting URL of the server, used for URL generation must be specified: -License -------- +```yaml +plausible_base_url: change-me +``` -BSD +Please define a long (>= 64 characters) secret key, which will be used by your instance to encrypt data: -Author Information ------------------- +```yaml +plausible_secret_key_base: change-me +``` -An optional section for the role authors to include contact information, or a website (HTML is not allowed). +# Email + +Plausible can send various emails; for this it needs a SMTP relay. Following variables define the SMTP account from which emails will be sent: + +```yaml +plausible_smtp_host: +plausible_smtp_port: 587 +plausible_smtp_username: +plausible_smtp_password: +``` + +If you don't define any, no emails will be sent and you'll need to look through the logs :) + +The email on behalf of which messages are sent is defined by: + +```yaml +plausible_smtp_email: "changeme@example.com" +``` + +## Database + +Plausible depends on PostgreSQL and Clickhouse. + +For PostgreSQL, you need to specify following variables: + +```yaml +plausible_db_host: "plausible_db" +plausible_db: "plausible" +plausible_db_password: "change_me" +``` +If you want to expose the database port outside (e.g. for backup), please define `plausible_db_port` + + +For Clickhouse, you only need to define the version used: + +```yaml +plausible_clickhouse_version: "21.3.2.5" +``` + +### Volumes + +The role will create following paths used by the docker containers as volumes: + +```yaml +plausible_volume_base: "/mnt/plausible" +plausible_volume_config: "{{ plausible_volume_base }}/config" +plausible_volume_db: "{{ plausible_volume_base }}/db_data" +plausible_volume_events: "{{ plausible_volume_base }}/event_data" +plausible_volume_geoip: "{{ plausible_volume_base }}/geoip_data" +``` + +The `plausible_volume_geoip` is necessary to access MaxMind GeoIP data (see below). + +### GeoIP + +Plausible defaults to DBIP, but can be configured to use MaxMind GeoIP. If you want to use MaxMind, you need to define: + +```yaml +plausible_geoip_db: "GeoLite2-Country.mmdb" +``` + +## Dependencies + +None + +## Example Playbook + +```yaml +--- +- name: Create unifi volume + hosts: services + vars: + plausible_port: "8100" + plausible_base_url: "https://metrics.example.com" + plausible_admin_user_email: "admin@example.com" + plausible_admin_user_name: "admin" + plausible_admin_user_pwd: "change-me" + roles: + - 'laurivan.plausible' +``` + +## License + +MIT + +## Author Information + +This role was created in 2022 by [Laur Ivan](https://www.laurivan.com). diff --git a/defaults/main.yml b/defaults/main.yml index 48a79a3..836ec73 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -1,6 +1,9 @@ --- # defaults file for plausible +# Plausible +plausible_version: "latest" + # Email plausible_smtp_host: plausible_smtp_port: 587 @@ -19,9 +22,13 @@ plausible_secret_key_base: change-me plausible_smtp_email: "changeme@example.com" # Database +plausible_db_port: +plausible_db_host: "plausible_db" +plausible_db: "plausible_db" +plausible_db_password: "change_me" plausible_clickhouse_version: "21.3.2.5" -plausible_version: "latest" -plausible_pg_password: "change_me" + + # Volumes plausible_volume_base: "/mnt/plausible" diff --git a/tasks/main.yml b/tasks/main.yml index 5f8caf6..c9e6d52 100644 --- a/tasks/main.yml +++ b/tasks/main.yml @@ -42,6 +42,7 @@ loop: - "env.plausible.conf" - "env.mail.conf" + - "env.db.conf" tags: - configuration diff --git a/templates/docker-compose.yml.j2 b/templates/docker-compose.yml.j2 index 87e8430..296ca10 100644 --- a/templates/docker-compose.yml.j2 +++ b/templates/docker-compose.yml.j2 @@ -13,8 +13,12 @@ services: restart: always volumes: - {{ plausible_volume_db }}:/var/lib/postgresql/data - environment: - - POSTGRES_PASSWORD={{ plausible_pg_password }} +{% if plausible_db_port %} + ports: + - {{ plausible_db_port }}:5432 +{% endif %} + env_file: + - {{ plausible_volume_config }}/env.db.conf networks: - plausible @@ -44,7 +48,7 @@ services: - {{ plausible_port }}:8000 env_file: - {{ plausible_volume_config }}/env.plausible.conf -{% if plausible_geoip_stat.stat.exists %} +{% if plausible_volume_geoip and plausible_geoip_db and plausible_geoip_stat.stat.exists %} volumes: - {{ plausible_volume_geoip }}/{{ plausible_geoip_db }}:/geoip:ro {% else %} diff --git a/templates/env.db.conf.j2 b/templates/env.db.conf.j2 new file mode 100644 index 0000000..fc54392 --- /dev/null +++ b/templates/env.db.conf.j2 @@ -0,0 +1,4 @@ +POSTGRES_USER=postgres +POSTGRES_PASSWORD={{ plausible_db_password }} + +POSTGRES_DB={{ plausible_db }} diff --git a/templates/env.plausible.conf.j2 b/templates/env.plausible.conf.j2 index caeda39..32c6137 100644 --- a/templates/env.plausible.conf.j2 +++ b/templates/env.plausible.conf.j2 @@ -4,12 +4,12 @@ ADMIN_USER_PWD={{ plausible_admin_user_pwd }} BASE_URL={{ plausible_base_url }} SECRET_KEY_BASE={{ plausible_secret_key_base }} -{% if plausible_geoip_stat.stat.exists %} +{% if plausible_volume_geoip and plausible_geoip_db and plausible_geoip_stat.stat.exists %} GEOLITE2_COUNTRY_DB={{ plausible_volume_geoip }}/{{ plausible_geoip_db }} {% endif %} # DB and events -DATABASE_URL=postgres://postgres:{{ plausible_pg_password }}@plausible_db:5432/plausible_db +DATABASE_URL=postgres://postgres:{{ plausible_db_password }}@{{ plausible_db_host }}:5432/{{ plausible_db }} CLICKHOUSE_DATABASE_URL=http://plausible_events_db:8123/plausible_events_db #SMTP