pub-solar/matrix-docker-ansible-deploy
5
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity
matrix-docker-ansible-deploy/docs/installing.md

6.1 KiB
Raw Blame History

Installing

If you've configured your DNS and have configured the playbook, 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 and executed by the make utility) which ultimately runs ansible-galaxy to download Ansible roles. If you don't have make, you can also manually run the roles commands seen in the Makefile.

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

Here are some playbook tags that you should be familiar with:

  • setup-all - runs all setup tasks for all components, but does not start/restart services

  • setup-SERVICE (e.g. setup-bot-postmoogle) - runs the setup tasks only for a given role, but does not start/restart services. You can discover these additional tags in each role (roles/*/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, setting up the mautrix-telegram bridge, in addition to the setup-mautrix-telegram tag, requires database changes (the setup-postgres tag) as well as reverse-proxy changes (the setup-nginx-proxy tag).

  • start - starts all systemd services and makes them start automatically in the future

  • stop - stops all systemd services

  • ensure-matrix-users-created - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created

setup-* 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.

1. Installing Matrix

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 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 Matrix server and you won't be importing old data into it, run all these tags:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

This will do a full installation and start all Matrix 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 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:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all

When this command completes, services won't be running yet.

You can now:

.. and then proceed to starting all services:

ansible-playbook -i inventory/hosts setup.yml --tags=start

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

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.

3. Finalize the installation

Now that services are running, you need to finalize the installation process (required for federation to work!) by Configuring Service Discovery via .well-known.

4. Things to do next

After you have started the services and finalized the installation process (required for federation to work!) by Configuring Service Discovery via .well-known, you can: