Installing

If you've configured the playbook and have prepared the required domains (DNS records) depending on the services you've enabled, you can start the installation procedure.

This playbook makes use of the just utility to make it easier to run playbook-related commands defined in the 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 utility): create setup.yml, requirements.yml and group_vars/mash_servers based on the up-to-date templates found in the templates/ directory. If you are using just, these files are created and maintained up-to-date automatically.
update the Ansible roles in this playbook by either running just update or git pull && just roles. just update is a shortcut that calls git pull and just roles with a single command, while just roles is a shortcut which ultimately runs either agru or ansible-galaxy 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.

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:

(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:

setup-all - runs all setup tasks (installation and uninstallation) for all components, but does not start/restart services
install-all - like setup-all, but skips uninstallation tasks. Useful for maintaining your setup quickly when its components remain unchanged. If you adjust your vars.yml to remove components, you'd need to run setup-all though, or these components will still remain installed
setup-SERVICE (e.g. setup-miniflux) - runs the setup tasks only for a given role (Miniflux in this example), but does not start/restart services. You can discover these additional tags in each role (roles/**/tasks/main.yml). Running per-component setup tasks is not recommended, as components sometimes depend on each other and running just the setup tasks for a given component may not be enough. For example, for setting up the Miniflux service, in addition to the setup-miniflux tag, changes to the database are also necessary (the setup-postgres tag).
install-SERVICE (e.g. install-miniflux) - like setup-SERVICE, but skips uninstallation tasks. See install-all above for additional information.
start - starts all systemd services and makes them start automatically in the future
stop - stops all systemd services

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 (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

There 2 ways to start the installation process - depending on whether you're Installing a brand new server (without importing data) or Installing a server into which you'll import old data.

Installing a brand new server (without importing data)

If this is a brand new server and you won't be importing old data into it, run all these tags:

# 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.

Proceed to Maintaining your setup in the future and Finalize the installation

Installing a server into which you'll import old data

If you will be importing data into your newly created 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 install-all tag:

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.

You can now:

Importing an existing Postgres database (from another installation) (optional)

.. and then proceed to starting all services:

# 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

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 use setup-all instead of install-all. See Playbook tags introduction

To do it with just:

just install-all

# Or, to run potential uninstallation tasks too:
# just setup-all

To do it without just:

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

After you have started the services, you can:

start using the configured services
or set up additional services
or learn how to upgrade services when new versions are released
or come say Hi in our Matrix support room - #mash-playbook:devture.com. You might learn something or get to help someone else new to hosting services with this playbook.
or help make this playbook better by contributing (code, documentation, or coffee/beer)

7.8 KiB Raw Permalink Blame History