We no longer ask users to create Matrix user accounts for these bots: - Postmoogle - Honoroit - Reminder Bot Other bots and services (matrix-registration-bot, maubot, mjolnir, Dimension, etc.) require an Access Token to run (not a password), so this new role doesn't help for them. It does help for the above bots though, and for defining your own "initial user accounts" in the `matrix_user_creator_users_additional` variable.
5.6 KiB
Installing
If you've configured your DNS and have configured the playbook, you can start the installation procedure.
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 thesetup-mautrix-telegram
tag, requires database changes (thesetup-postgres
tag) as well as reverse-proxy changes (thesetup-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:
-
Importing an existing SQLite database (from another Synapse installation) (optional)
-
Importing an existing Postgres database (from another installation) (optional)
-
Importing
media_store
data files from an existing Synapse installation (optional)
.. 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:
- check if services work
- or create your first Matrix user account
- or set up additional services (bridges to other chat networks, bots, etc.)
- or learn how to upgrade services when new versions are released
- or learn how to maintain your server
- or join some Matrix rooms:
- via the Explore rooms feature in Element or some other client, or by discovering them using this matrix-static list. Note: joining large rooms may overload small servers.
- or come say Hi in our support room - #matrix-docker-ansible-deploy:devture.com. You might learn something or get to help someone else new to Matrix hosting.
- or help make this playbook better by contributing (code, documentation, or coffee/beer)