diff --git a/README.md b/README.md index 13a0cdd..15a3209 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,59 @@ # Ansible Playbook for Pleroma +## Table of content + +- [Summary](#summary) +- [Requirements](#requirements) +- [Configuration](#configuration) +- [Secrets](#secrets) +- [Guide to setting up and running the playbook](#guide-to-setting-up-and-running-the-playbook) + ## Summary -This project was inspired by the official [Pleroma OTP installation guide](https://docs.pleroma.social/otp_en.html#content) -and contains a playbook which installs and configures Pleroma on a single Alpine Linux host. -It currently contains four roles, including: +This project is a configurable playbook that can install, configure and customise Pleroma on an Alpine Linux host. +The playbook is currently used to manage my personal instance at https://fedi.dananglin.me.uk. +It currently only supports installing Pleroma on a single host but will support installing it across multipe hosts in the future. -- **init:** merges the default configuration with the user's custom configuration. -- **pleroma-postgres:** installs and configures the PostgreSQL database. -- **pleroma-main:** installs/upgrades Pleroma and configures both the backend and frontend. -- **pleroma-nginx:** installs and configures Nginx, creates SSL certificates using Let's Encrypt and adds support for proving your Pleroma site with Keybase. +This project was inspired by the official [Pleroma OTP installation guide](https://docs.pleroma.social/otp_en.html#content). -This project is currently used to manage my personal instance at https://fedi.dananglin.me.uk. +This project is developed over at https://gitlab.com/dananglin/pleroma-ansible-playbook. The master branch is mirrored over at https://github.com/dananglin/pleroma-ansible-playbook. -## Additional Features +The project's icon ([Books icon](https://icons8.com/icon/114010/books)) was downloaded from [Icons8](https://icons8.com). -- **Let's Encrypt support:** This playbook creates a SSL certificate using Let's Encrypt. +### Ansible roles + +There are four roles used to install and configure your Pleroma instance: + +- **init:** merges the default configuration with your custom configuration. +- **pleroma-database:** maintains the database layer by installing and configuring the PostgreSQL database server, creating the database user and creating and administrating the Pleroma database. +- **pleroma-main:** maintains the main layer by handling the Pleroma installation, Pleroma upgrades and the configuration of the Pleroma frontend and backend. +- **pleroma-proxy:** maintains the proxy layer by installing and configuring Nginx, creating the TLS certificates using Let's Encrypt, adding support for proving your Pleroma site with Keybase, etc. + +### Additional features + +- **Let's Encrypt support:** This playbook creates a TLS certificate using Let's Encrypt. - **Keybase support:** Pleroma does not support Keybase out of the box but you can still prove that your ownership of your Pleroma site. -- **Custom default background:** Specify an image to use as the default background of your Pleroma site. +- **Set default background:** You can specify an image to use as the default background of your Pleroma site. +- **Upload custom themes:** You can upload custom Pleroma themes in to your Pleroma instance. +- **Set default theme:** You can specify the default Pleroma theme. ## Requirements -- A controller host running [Ansible](https://www.ansible.com/) version 2.8+. -- `make` and `openssl` on the controller host which are used to generate secret values. -- A target host running [Alpine Linux](https://www.alpinelinux.org/) version 3.10. +### For your controller host + +- The controller host should the following packages installed: + - [Ansible](https://www.ansible.com/) version 2.8+. + - make + - openssl + +### For your target Pleroma host + +- The target host should be running [Alpine Linux](https://www.alpinelinux.org/) version 3.10+. - A (sub)domain which resolves to the IP address of the target host. +- A user with sudo privileges (optional, but preferable). +- The following packages installed: + - sudo + - python (version 3.5 or higher) ## Configuration @@ -44,7 +73,7 @@ Following secrets are not included in the default configuration and must be gene - **vapid key pair for web push encryption:** This is a private and public key pair so that Pleroma can used [VAPID](https://tools.ietf.org/html/rfc8292) to identify itself to the web push service (for notifications in the browser). - **database password:** This is used to authenticate access to the Pleroma database. -Insstructions on generating these can be found in the guide below. +Instructions on generating these can be found in the guide below. It is recommended to encrypt these secrets using [Ansible Vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html). ## Guide to setting up and running the playbook @@ -54,7 +83,7 @@ It is recommended to encrypt these secrets using [Ansible Vault](https://docs.an $ cp examples/inventory.yml ./ ``` -- In the inventory file you've just copied change **\** to the IP address of the target host and change **\** to the user on the target host with sudo priviledges. +- In the inventory file you've just copied change **\** to the IP address of the target host and change **\** to the user on the target host with sudo privileges. - Copy the [example playbook file](examples/site.yml) to the root of the project. ```bash