diff --git a/docs/installing.md b/docs/installing.md index 3bbc9a44c..7e2edf6c5 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -2,7 +2,7 @@ If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playbook.md), you can start the installation procedure. -**Before installing** and each time you update the playbook in the future, you will need to update the Ansible roles in this playbook by running `make roles`. `make roles` is a shortcut (a `roles` target defined in [`Makefile`](Makefile) and executed by the [`make`](https://www.gnu.org/software/make/) utility) which ultimately runs [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to download Ansible roles. If you don't have `make`, you can also manually run the `roles` commands seen in the `Makefile`. +**Before installing** and each time you update the playbook in the future, you will need to update the Ansible roles in this playbook by running `just roles`. `just roles` is a shortcut (a `roles` target defined in [`justfile`](justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately runs [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to download Ansible roles. If you don't have `just`, you can also manually run the `roles` commands seen in the `justfile`. ## Playbook tags introduction @@ -57,7 +57,7 @@ Proceed to [Maintaining your setup in the future](#2-maintaining-your-setup-in-t If you will be importing data into your newly created Matrix server, install it, but **do not** start its services just yet. Starting its services or messing with its database now will affect your data import later on. -To do the installation **without** starting services, run only the `setup-all` tag: +To do the installation **without** starting services, run only the `install-all` tag: ```sh ansible-playbook -i inventory/hosts setup.yml --tags=install-all @@ -88,6 +88,8 @@ Feel free to **re-run the setup command any time** you think something is off wi Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [Playbook tags introduction](#playbook-tags-introduction) +A way to invoke these `ansible-playbook` commands with less typing in the future is to use [just](https://github.com/casey/just) to run them: `just install-all` or `just setup-all`. See [our `justfile`](../../justfile) for more information. + ## 3. Finalize the installation diff --git a/docs/maintenance-upgrading-services.md b/docs/maintenance-upgrading-services.md index d1c707fd6..b65eadd77 100644 --- a/docs/maintenance-upgrading-services.md +++ b/docs/maintenance-upgrading-services.md @@ -10,8 +10,8 @@ To upgrade services: - take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of -- download the upstream Ansible roles used by the playbook by running `make roles` +- download the upstream Ansible roles used by the playbook by running `just roles` -- re-run the [playbook setup](installing.md) and restart all serivces: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start` +- re-run the [playbook setup](installing.md) and restart all services: `just setup-all` **Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql). diff --git a/docs/prerequisites.md b/docs/prerequisites.md index c0a906408..83ae42dae 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -22,7 +22,7 @@ If your distro runs within an [LXC container](https://linuxcontainers.org/), you - [`git`](https://git-scm.com/) is the recommended way to download the playbook to your computer. `git` may also be required on the server if you will be [self-building](self-building.md) components. -- [`make`](https://www.gnu.org/software/make/) for running `make roles`, etc. (see [`Makefile`](../Makefile)), although you can also run these commands manually (without `make`) +- [`just`](https://github.com/casey/just) for running `just roles`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually - An HTTPS-capable web server at the base domain name (``) which is capable of serving static files. Unless you decide to [Serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md) or alternatively, to use DNS SRV records for [Server Delegation](howto-server-delegation.md). diff --git a/docs/registering-users.md b/docs/registering-users.md index 321346b65..51fdef346 100644 --- a/docs/registering-users.md +++ b/docs/registering-users.md @@ -16,13 +16,21 @@ Table of contents: You can do it via this Ansible playbook (make sure to edit the `` and `` part below): +```sh +just register-user + +# Example: `just register-user john secret-password yes` ``` + +**or** by invoking `ansible-playbook` manually: + +```sh ansible-playbook -i inventory/hosts setup.yml --extra-vars='username= password= admin=' --tags=register-user ``` **or** using the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)): -``` +```sh /matrix/synapse/bin/register-user ``` diff --git a/justfile b/justfile new file mode 100644 index 000000000..4b6dfbfb1 --- /dev/null +++ b/justfile @@ -0,0 +1,44 @@ +# Shows help +default: + @just --list --justfile {{ justfile() }} + +# Pulls external Ansible roles +roles: + rm -rf roles/galaxy + ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force + +# Runs ansible-lint against all roles in the playbook +lint: + ansible-lint + +# Runs the playbook with --tags=install-all,ensure-matrix-users-created,start and optional arguments +install-all *extra_args: (run-tags "install-all,ensure-matrix-users-created,start" extra_args) + +# Runs the playbook with --tags=setup-all,ensure-matrix-users-created,start and optional arguments +setup-all *extra_args: (run-tags "setup-all,ensure-matrix-users-created,start" extra_args) + +# Runs the playbook with the given list of arguments +run +extra_args: + time ansible-playbook -i inventory/hosts setup.yml {{ extra_args }} + +# Runs the playbook with the given list of comma-separated tags and optional arguments +run-tags tags *extra_args: + just --justfile {{ justfile() }} run --tags={{ tags }} {{ extra_args }} + +# Runs the playbook in user-registration mode +register-user username password admin_yes_or_no *extra_args: + time ansible-playbook -i inventory/hosts setup.yml --tags=register-user --extra-vars="username={{ username }} password={{ password }} admin={{ admin_yes_or_no }}" {{ extra_args }} + +# Starts all services +start-all *extra_args: (run-tags "start-all" extra_args) + +# Starts a specific service group +start-group group *extra_args: + @just --justfile {{ justfile() }} run-tags start-group --extra-vars="group={{ group }}" {{ extra_args }} + +# Stops all services +stop-all *extra_args: (run-tags "stop-all" extra_args) + +# Stops a specific service group +stop-group group *extra_args: + @just --justfile {{ justfile() }} run-tags stop-group --extra-vars="group={{ group }}" {{ extra_args }} diff --git a/playbooks/matrix.yml b/playbooks/matrix.yml index 1723d8afe..409328aec 100755 --- a/playbooks/matrix.yml +++ b/playbooks/matrix.yml @@ -4,7 +4,7 @@ become: true roles: - # Most of the roles below are not distributed with the playbook, but downloaded separately using `ansible-galaxy` via the `make roles` command (see `Makefile`). + # Most of the roles below are not distributed with the playbook, but downloaded separately using `ansible-galaxy` via the `just roles` command (see `justfile`). - role: galaxy/com.devture.ansible.role.playbook_help - role: galaxy/com.devture.ansible.role.systemd_docker_base