Encourage using just, and mention that not using it requires syncing with template/ files

docs/ansible.md

@@ -54,7 +54,7 @@ Docker is normally installed by the playbook, so this may be a bit of a chicken
 Once you have a working Docker installation on the server, **clone the playbook** somewhere on the server and configure it as per usual (`inventory/hosts`, `inventory/host_vars/..`, etc.), as described in [configuring the playbook](configuring-playbook.md).
 
 You would then need to add `ansible_connection=community.docker.nsenter` to the host line in `inventory/hosts`. This tells Ansible to connect to the "remote" machine by switching Linux namespaces with [nsenter](https://man7.org/linux/man-pages/man1/nsenter.1.html), instead of using SSH.
-Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `ansible-playbook --connection=community.docker.nsenter ...`
+Alternatively, you can leave your `inventory/hosts` as is and specify the connection type in **each** `ansible-playbook` call you do later, like this: `just install-all --connection=community.docker.nsenter` (or `ansible-playbook --connection=community.docker.nsenter ...`).
 
 Run this from the playbook's directory:
 
@@ -73,7 +73,7 @@ The `/work` directory contains the playbook's code.
 
 First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
 
-Finally, you can execute `ansible-playbook ...` (or `ansible-playbook --connection=community.docker.nsenter ...`) commands as per normal now.
+Finally, you can execute `just` or `ansible-playbook ...` (e.g. `ansible-playbook --connection=community.docker.nsenter ...`) commands as per normal now.
 
 
 ### Running Ansible in a container on another computer (not the server)
@@ -97,7 +97,7 @@ The `/work` directory contains the playbook's code.
 
 First, consider running `git config --global --add safe.directory /work` to [resolve directory ownership issues](#resolve-directory-ownership-issues).
 
-Finally, you execute `ansible-playbook ...` commands as per normal now.
+Finally, you execute `just` or `ansible-playbook ...` commands as per normal now.
 
 
 #### If you don't use SSH keys for authentication

docs/installing.md

@@ -2,14 +2,25 @@
 
 If you've [configured the playbook](configuring-playbook.md) and have prepared the required domains (DNS records) depending on the services you've enabled, 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 `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`.
+This playbook makes use of the [`just`](https://github.com/casey/just) utility to make it easier to run playbook-related commands defined in the [`justfile`](../justfile).
+We recommend installing and using using `just` - otherwise, you'll need to do more manual work.
+
+**Before installing** and each time you update the playbook in the future, you will need to:
+
+- (only if you're not using the [`just`](https://github.com/casey/just) utility): create `setup.yml`, `requirements.yml` and `group_vars/mash_servers` based on the up-to-date templates found in the [`templates/` directory](../templates). If you are using `just`, these files are created and maintained up-to-date automatically.
+
+- update the Ansible roles in this playbook by running `just roles`. `just roles` is a shortcut which ultimately runs [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to download Ansible roles defined in the `requirements.yml` file. If you don't have `just`, you can also manually run the `roles` commands seen in the [`justfile`](../justfile).
 
 
 ## Playbook tags introduction
 
 The Ansible playbook's tasks are tagged, so that certain parts of the Ansible playbook can be run without running all other tasks.
 
-The general command syntax is: `ansible-playbook -i inventory/hosts setup.yml --tags=COMMA_SEPARATED_TAGS_GO_HERE`
+The general command syntax is:
+
+- (**recommended**) when using `just`: `just run-tags COMMA_SEPARATED_TAGS_GO_HERE`
+
+- when not using `just`: `ansible-playbook -i inventory/hosts setup.yml --tags=COMMA_SEPARATED_TAGS_GO_HERE`
 
 Here are some playbook tags that you should be familiar with:
 
@@ -27,10 +38,22 @@ Here are some playbook tags that you should be familiar with:
 
 `setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc.
 
+When using `just`, there are also helpful shortcuts you can use:
+
+- `just install-all`: runs all installation tasks and starts/restarts the services
+
+- `just setup-all`: runs all installation tasks and also uninstallation tasks that clean up after services you have removed from your `vars.yml` file. This task also starts/restarts all services.
+
+- `just install-service SERVICE_NAME`: runs the installation tasks only for the `SERVICE_NAME` service and starts/restarts the service. As mentioned above, this is not usually recommended, as installing a service may require running installation tasks for other (dependent) roles to prepare a database, etc.
+
+- `just stop-all`: stops all services
+
+- `just start-all`: starts all services
+
 
 ## 1. Installing services
 
-If you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the all Ansible commands
+If you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the all Ansible (or `just`) commands
 
 If you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to all Ansible commands
 
@@ -42,7 +65,11 @@ There 2 ways to start the installation process - depending on whether you're [In
 If this is **a brand new** server and you **won't be importing old data into it**, run all these tags:
 
 ```sh
-ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
+# This is equivalent to: just run-tags install-all,start
+just install-all
+
+# Or, when not using just, you can use this instead:
+# ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
 ```
 
 This will do a full installation and start all services.
@@ -58,10 +85,13 @@ Starting its services or messing with its database now will affect your data imp
 To do the installation **without** starting services, run only the `install-all` tag:
 
 ```sh
-ansible-playbook -i inventory/hosts setup.yml --tags=install-all
+just run-tags install-all
+
+# Or, when not using just, you can use this instead:
+# ansible-playbook -i inventory/hosts setup.yml --tags=install-all
 ```
 
-When this command completes, services won't be running yet.
+When this command completes, **services won't be running yet**.
 
 You can now:
 
@@ -70,7 +100,11 @@ You can now:
 .. and then proceed to starting all services:
 
 ```sh
-ansible-playbook -i inventory/hosts setup.yml --tags=start
+# This is equivalent to: just run-tags start (or: just run-tags start-all)
+just start-all
+
+# Or, when not using just, you can use this instead:
+# ansible-playbook -i inventory/hosts setup.yml --tags=start
 ```
 
 Proceed to [Maintaining your setup in the future](#2-maintaining-your-setup-in-the-future).
@@ -80,9 +114,25 @@ Proceed to [Maintaining your setup in the future](#2-maintaining-your-setup-in-t
 
 Feel free to **re-run the setup command any time** you think something is off with the server configuration. Ansible will take your configuration and update your server to match.
 
-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)
+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 use `setup-all` instead of `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.
+To do it with `just`:
+
+```sh
+just install-all
+
+# Or, to run potential uninstallation tasks too:
+# just setup-all
+```
+
+To do it without `just`:
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
+
+# Or, to run potential uninstallation tasks too:
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
 
 
 ## 3. Things to do next

docs/prerequisites.md

@@ -22,9 +22,9 @@ If your distro runs within an [LXC container](https://linuxcontainers.org/), you
 
 - the [passlib](https://passlib.readthedocs.io/en/stable/index.html) Python library installed on the computer you run Ansible. On most distros, you need to install some `python-passlib` or `py3-passlib` package, etc.
 
-- [`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.
+- [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.
 
-- [`just`](https://github.com/casey/just) for running `just roles`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually
+- [just](https://github.com/casey/just) for running `just roles` and playbook installation commands, etc. (see [`justfile`](../justfile)). You can get by without `just` (by running `ansible-galaxy`, `ansible-playbook` commands manually), but maintaining your playbook setup will require more manual work. `just` (thanks to the commands defined in the `justfile`) keeps various files (`setup.yml`, `requirements.yml`, `group_vars/mash_servers`) up-to-date with the templates in [the `templates/` directory](../templates/) automatically.
 
 - at least one domain name you can use