From a1f9869eb2ae7f9d82a6e2fb50fed4340b6c040a Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Sun, 10 Mar 2019 17:02:17 +0200 Subject: [PATCH] Improve documentation about getting the playbook --- docs/README.md | 4 +++- docs/configuring-playbook.md | 8 +++++-- docs/getting-the-playbook.md | 41 ++++++++++++++++++++++++++++++++++++ docs/prerequisites.md | 2 +- 4 files changed, 51 insertions(+), 4 deletions(-) create mode 100644 docs/getting-the-playbook.md diff --git a/docs/README.md b/docs/README.md index 35ba609a8..1718c6ace 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,9 @@ - [Configuring your DNS server](configuring-dns.md) -- [Configuring this Ansible playbook](configuring-playbook.md) +- [Getting this playbook's source code](getting-the-playbook.md) + +- [Configuring the playbook](configuring-playbook.md) - [Installing](installing.md) diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 3da733b24..4951d8d4e 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -1,8 +1,12 @@ # Configuring the Ansible playbook -Once you have your server and you have [configured your DNS records](configuring-dns.md), you can proceed with configuring this playbook, so that it knows what to install and where. +To configure the playbook, you need to have done the following things: -You can follow these steps: +- have a server where Matrix services will run +- [configured your DNS records](configuring-dns.md) +- [retrieved the playbook's source code](getting-the-playbook.md) to your computer + +You can then follow these steps inside the playbook directory: - create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.`) diff --git a/docs/getting-the-playbook.md b/docs/getting-the-playbook.md new file mode 100644 index 000000000..2541da0da --- /dev/null +++ b/docs/getting-the-playbook.md @@ -0,0 +1,41 @@ +# Getting the playbook + +This Ansible playbook is meant to be executed on your own computer (not the Matrix server). + +In special cases (if your computer cannot run Ansible, etc.) you may put the playbook on the server as well. + +You can retrieve the playbook's source code by: + +- [Using git to get the playbook](#using-git-to-get-the-playbook) (recommended) + +- [Downloading the playbook as a ZIP archive](#downloading-the-playbook-as-a-zip-archive) (not recommended) + + +## Using git to get the playbook + +We recommend using the [git](https://git-scm.com/) tool to get the playbook's source code, because it lets you easily keep up to date in the future when [Maintaining services](maintenance-upgrading-services.md). + +Once you've installed git on your computer, you can go to any directory of your choosing and run the following command to retrieve the playbook's source code: + +```bash +git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git +``` + +This will create a new `matrix-docker-ansible-deploy` directory. +You're supposed to execute all other installation commands inside that directory. + + +## Downloading the playbook as a ZIP archive + +Alternatively, you can download the playbook as a ZIP archive. +This is not recommended, as it's not easy to keep up to date with future updates. We suggest you [use git](#using-git-to-get-the-playbook) instead. + +The latest version is always at the following URL: https://github.com/spantaleev/matrix-docker-ansible-deploy/archive/master.zip + +You can extract this archive anywhere. You'll get a directory called `matrix-docker-ansible-deploy-master`. +You're supposed to execute all other installation commands inside that directory. + + +--------------------------------------------- + +No matter which method you've used to download the playbook, you can proceed by [Configuring the playbook](configuring-playbook.md). diff --git a/docs/prerequisites.md b/docs/prerequisites.md index f021a87df..cf270e5d8 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -4,7 +4,7 @@ - [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python`). -- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for [version requirements](ansible.md#supported-ansible-versions) or alternative ways to run Ansible. +- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible. - either the `dig` tool or `python-dns` installed on your own computer. Used later on, by the playbook's [services check](maintenance-checking-services.md) feature.