mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2024-12-27 03:18:31 +01:00
Add "Quick start" guide (#3801)
* Add docs/quick-start.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Add description about keeping the playbook and services up-to-date
Also: move descriptions about difference between the playbook tags (setup-all and install-all) and about the just "recipe" from installing.md to maintenance-upgrading-services.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Replace <your-username> with YOUR_USERNAME_HERE
This is a common expression and should avoid misunderstanding that `<` and `>` would need to be included
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Replace <your-password> with YOUR_PASSWORD_HERE
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Change the link to 'Quick start' on the breadcrumbs from README.md to quick-start.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Add a link to quick-start.md on the "Getting started" section
Since I am not quite sure whether the link to prerequisites.md should be replaced in favor of this link, this commit leaves it as it is for now.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Add a link to quick-start.md on docs/README.md
Since I am not quite sure whether the link to prerequisites.md should be replaced in favor of this link, this commit leaves it as it is for now.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Add note about using "example.com" as an example domain
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Remove backticks from command examples to register a user
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Apply suggestions from code review
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
* Improve notes for instruction to create a user account
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Add details about delegation to installing.md and quick-start.md
Some information is omitted on quick-start.md in favor of installing.md to keep the quick start guide simple.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/quick-start.md: add the breadcrumb header
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Edit docs/quick-start.md: run the setup command with install-all by default
Refer docs/maintenance-upgrading-services.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Revert "Update docs/quick-start.md: add the breadcrumb header"
This reverts commit 9a6e1cf14c.
As the quick start guide is standalone.
* Update docs/quick-start.md: add headers inside the install section
These headers should make it perfectly clear that there are two steps to be done to install with the playbook
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update quick-start.md
* Update docs/registering-users.md: notes for manual user registeration
Copy the same notes from quick-start.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Reword some things in quick start
* Add alternative to `just roles`
* Update docs/configuring-dns.md: sync with docs/quick-start.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/quick-start.md: add a link to docs/registering-users.md for an instruction to add user accounts
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/registering-users.md and docs/updating-users-passwords.md: remove "your" from username and password placeholders
These documentations, unlike docs/installing.md and docs/quick-start.md, describe how to handle users (registering them or changing their passwords), some of whom are yours, while others are not.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/installing.md: add "your" to make it clear that it is "your" account that is going to be created
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/installing.md and docs/quick-start.md: mention "make roles"
This commit adds mentions to "make roles" and a note about the preference of ansible-playbook commands over the just "recipes".
quick-start.md intends to be referred by those who have never used the playbook to set up a server, so it is safer to regard that it is not clear to them what exactly the just "recipes" are made of, ie. it takes some time and experience until someone understands simplicity of them. For beginners, I believe that we should prefer the basics over simplicity, from the educational point of view.
If someone feels tired of using the same command repetitively, then the person will have been already well accustomed to the way how the playbook works and how the server is supposed to be maintained, and the person is "qualified" to use the just "recipes", and should be able to use them with confidence, distinguishing the playbook tags from the "recipes", for example, from "just install-all" and "ansible-playbook -i inventory/hosts setup.yml --tags=install-all". Such level of familiarity and experience should not be expected on the quick start guide.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update instructions to update Ansible roles
Also: move the detailed explanation about "just roles" from installing.md to maintenance-upgrading-services.md
TBD: create a dedicated documentation for the "just" program and the concept of its "recipe" (shortcut of commands)
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Add a note about cases to create multiple accounts/users
Since one of the quick start guide's goals is to set up an own user account, this commit adds the note about creating multiple accounts/users to installing.md and registering-users.md only. It should be fine as registering-users.md is linked from quick-start.md
Also:
- On installing.md and quick-start.md, change instruction from what encourages to select "admin=yes" or "admin=no" to what encourages to use "admin=yes", since your user account will be the sole user on the server, as long as you set up the server by following the documentation
- Remove the link to registering-users.md from quick-start.md as the documentation is already linked above, under the header of the section
- Sync docs/installing.md with other documentation
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Remove a line about setting "admin=yes" to reduce the amount of information
Because quick-start.md is getting longer with much information, it removes the note in favor of the linked registering-users.md documentation. The note is available on installing.md as well, and details about adding user accounts for other people can (and should) be checked on those documentations.
Also, this commit edits lines above these notes to make it clear that your user account will be an administrator of the server.
With this commit, the amount of the information about adding user accounts will be: registering-users.md > installing.md > quick-start.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Fix a broken anchor link on docs/installing.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Replace repetitive information about upgrading with an anchor link to docs/maintenance-upgrading-services.md
Because details to update/upgrade the Matrix services is not necessary for quick start and the amount of information should be reduced from the viewpoint of maintainability, this commit removes details to update/upgrade from quick-start.md
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/quick-start.md: add a note about keeping it tidy and simple
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/maintenance-checking-services.md and docs/quick-start.md: add instruction to use federation tester against the base domain
Per Slavi's suggestion.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/installing.md and docs/quick-start.md: replace commands to finalize the installation
Per Slavi's suggestion.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Clarify install-matrix-static-files to avoid confusion with install-all; Minor consistency improvements
---------
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
This commit is contained in:
Suguru Hirahara
GitHub
parent
7b6972aea5
commit
194a3ca461
@ -27,6 +27,8 @@ While the [list of supported services](#-supported-services) and documentation i
|
||||
- Starting with the basics. You can always add/remove or tweak services later on.
|
||||
- Following our guided installation, starting with the [Prerequisites](./docs/prerequisites.md) documentation page
|
||||
|
||||
If you have never configured Matrix services, follow the [**quick start**](./docs/quick-start.md) guide to set up minimum core services on your server.
|
||||
|
||||
## ✔ Supported services
|
||||
|
||||
Using this playbook, you can get the following list of services configured on your server. Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
|
||||
- [FAQ](faq.md) - lots of questions and answers. Jump to [Prerequisites](prerequisites.md) to avoid reading too much and to just start a guided installation.
|
||||
|
||||
- [Quick start](quick-start.md) - follow the guide to set up minimum core services on your server
|
||||
|
||||
- [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook
|
||||
|
||||
- [Configuring your DNS settings](configuring-dns.md)
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Configuring your DNS settings
|
||||
|
||||
<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > Configuring your DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
|
||||
<sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > Configuring your DNS settings > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
|
||||
|
||||
To set up Matrix on your domain, you'd need to do some DNS configuration.
|
||||
|
||||
@ -36,7 +36,7 @@ The `element.example.com` subdomain is necessary, because this playbook installs
|
||||
|
||||
Be mindful as to how long it will take for the DNS records to propagate.
|
||||
|
||||
If you are using Cloudflare DNS, make sure to disable the proxy and set all records to `DNS only`. Otherwise, fetching certificates will fail.
|
||||
If you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only". Otherwise, fetching certificates will fail.
|
||||
|
||||
## DNS settings for optional services/features
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Configuring the playbook
|
||||
|
||||
<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > Configuring the playbook > [Installing](installing.md)</sup>
|
||||
<sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > Configuring the playbook > [Installing](installing.md)</sup>
|
||||
|
||||
If you've configured your DNS records and retrieved the playbook's source code to your computer, you can start configuring the playbook. To do so, follow these steps inside the playbook directory:
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Getting the playbook
|
||||
|
||||
<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > Getting the playbook > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
|
||||
<sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > Getting the playbook > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
|
||||
|
||||
This Ansible playbook is meant to be executed on your own computer (not the Matrix server).
|
||||
|
||||
|
||||
@ -1,16 +1,19 @@
|
||||
# Installing
|
||||
|
||||
<sup>⚡️[Quick start](README.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > Installing</sup>
|
||||
<sup>⚡️[Quick start](quick-start.md) | [Prerequisites](prerequisites.md) > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > Installing</sup>
|
||||
|
||||
If you've configured your DNS records and the playbook, you can start the installation procedure.
|
||||
|
||||
## Update Ansible roles
|
||||
|
||||
Before installing, you need to update the Ansible roles in this playbook by running `just roles`.
|
||||
Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside.
|
||||
|
||||
`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 [agru](https://github.com/etkecc/agru) or [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) (depending on what is available in your system) to download Ansible roles. If you don't have `just`, you can also manually run the `roles` commands seen in the `justfile`.
|
||||
To update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file), run:
|
||||
|
||||
There's another shortcut (`just update`) which updates the playbook (`git pull`) and updates roles (`just roles`) at the same time.
|
||||
- either: `just update`
|
||||
- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
|
||||
|
||||
If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
|
||||
|
||||
## Install Matrix server and services
|
||||
|
||||
@ -74,18 +77,21 @@ As you have configured your brand new server and the client, you need to **creat
|
||||
|
||||
After creating the user account, you can log in to it with [Element Web](configuring-playbook-client-element-web.md) that this playbook has installed for you at this URL: `https://element.example.com/`.
|
||||
|
||||
To register a user via this Ansible playbook, run the command below on your local computer.
|
||||
To create your user account (as an administrator of the server) via this Ansible playbook, run the command below on your local computer.
|
||||
|
||||
**Notes**:
|
||||
- Before running it, make sure to edit `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
|
||||
- In the command below, `YOUR_USERNAME_HERE` is just a plain username (like `john`), not your full `@user:example.com` identifier
|
||||
- Make sure to adjust `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
|
||||
- For `YOUR_USERNAME_HERE`, use a plain username like `john`, not your full identifier (`@user:example.com`)
|
||||
- Use `admin=yes` to make your user account an administrator of the Matrix server
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=<yes|no>' --tags=register-user
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=yes' --tags=register-user
|
||||
|
||||
# Example: `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user`
|
||||
# Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
|
||||
```
|
||||
|
||||
Feel free to create as many accounts (for friends, family, etc.) as you want. Still, perhaps you should grant full administrative access to your account only (with `admin=yes`), and others should be created with `admin=no`.
|
||||
|
||||
For more information, see the documentation for [registering users](registering-users.md).
|
||||
|
||||
## Finalize the installation
|
||||
@ -94,20 +100,21 @@ Now you've configured Matrix services and your user account, you need to **final
|
||||
|
||||
This is required for federation to work! Without a proper configuration, your server will effectively not be part of the Matrix network.
|
||||
|
||||
If you need the base domain for anything else such as hosting a website, you have to configure it manually, following the procedure described on the linked documentation.
|
||||
To configure the delegation, you have these two options. Choose one of them according to your situation.
|
||||
|
||||
However, if you do not need the base domain for anything else, the easiest way of configuring it is to [serve the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server. It will enable you to use a Matrix user identifier like `@<username>:example.com` while hosting services on a subdomain like `matrix.example.com`.
|
||||
- If you can afford to point the base domain at the Matrix server, follow the instructions below which guide you into [serving the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server. It will enable you to use a Matrix user identifier like `@<username>:example.com` while hosting services on a subdomain like `matrix.example.com`.
|
||||
- Alternatively, if you're using the base domain for other purposes and cannot point it to the Matrix server (and thus cannot "serve the base domain" from it), you most likely need to [manually install well-known files on the base domain's server](configuring-well-known.md#manually-installing-well-known-files-on-the-base-domains-server), but feel free to familiarize yourself with all [server delegation (redirection) options](howto-server-delegation.md).
|
||||
|
||||
To configure server delegation in this way, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
To have the base domain served from the integrated web server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_static_files_container_labels_base_domain_enabled: true
|
||||
```
|
||||
|
||||
After configuring the playbook, run the installation command:
|
||||
After configuring the playbook, run the command below:
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=install-matrix-static-files,start
|
||||
```
|
||||
|
||||
## Things to do next
|
||||
@ -125,8 +132,12 @@ After finilizing the installation, you can:
|
||||
|
||||
### 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. To update the playbook and the Ansible roles in the playbook, simply run `just roles`.
|
||||
While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.
|
||||
|
||||
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 [this page on the playbook tags](playbook-tags.md) for more information.
|
||||
The upstream projects, which this playbook makes use of, occasionally if not often suffer from security vulnerabilities.
|
||||
|
||||
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 the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information.
|
||||
Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
|
||||
|
||||
For more information about upgrading or maintaining services with the playbook, take at look at this page: [Upgrading the Matrix services](maintenance-upgrading-services.md)
|
||||
|
||||
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.
|
||||
|
||||
@ -10,4 +10,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=self-check
|
||||
|
||||
If it's all green, everything is probably running correctly.
|
||||
|
||||
Besides this self-check, you can also check your server using the [Federation Tester](https://federationtester.matrix.org/).
|
||||
Besides this self-check, you can also check whether your server federates with the Matrix network by using the [Federation Tester](https://federationtester.matrix.org/) against your base domain (`example.com`), not the `matrix.example.com` subdomain.
|
||||
|
||||
@ -2,17 +2,39 @@
|
||||
|
||||
This playbook not only installs the various Matrix services for you, but can also upgrade them as new versions are made available.
|
||||
|
||||
While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.
|
||||
|
||||
The upstream projects, which this playbook makes use of, occasionally if not often suffer from security vulnerabilities (for example, see [here](https://github.com/element-hq/element-web/security) for known ones on Element Web).
|
||||
|
||||
Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
|
||||
|
||||
The developers of this playbook strive to maintain the playbook updated, so that you can re-run the playbook to address such vulnerabilities. It is **your responsibility** to keep your server and the services on it up-to-date.
|
||||
|
||||
If you want to be notified when new versions of Synapse are released, you should join the Synapse Homeowners room: [#homeowners:matrix.org](https://matrix.to/#/#homeowners:matrix.org).
|
||||
|
||||
To upgrade services:
|
||||
## Steps to upgrade the Matrix services
|
||||
|
||||
Before updating the playbook and the Ansible roles in the playbook, 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.
|
||||
|
||||
If it looks good to you, go to the `matrix-docker-ansible-deploy` directory, then:
|
||||
|
||||
- update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) using:
|
||||
|
||||
- either: `just update`
|
||||
- or: a combination of `git pull` and `just roles` (or `make roles`)
|
||||
- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
|
||||
|
||||
- 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
|
||||
`just update` and `just roles` are shortcuts (their targets are defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately run [agru](https://github.com/etkecc/agru) or [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) (depending on what is available in your system) to download Ansible roles, after upgrading the playbook (in case of `just update`).
|
||||
|
||||
- re-run the [playbook setup](installing.md) and restart all services: `just install-all` or `just setup-all`
|
||||
If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
|
||||
|
||||
- re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services:
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
|
||||
```
|
||||
|
||||
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 [this page on the playbook tags](playbook-tags.md) for more information.
|
||||
|
||||
A way to invoke these `ansible-playbook` commands with less typing is to use [just](https://github.com/casey/just) to run the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information. If you don't have `just`, you can also manually run the commands seen in the `justfile`.
|
||||
|
||||
**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).
|
||||
|
||||
@ -1,9 +1,11 @@
|
||||
# Prerequisites
|
||||
|
||||
<sup>⚡️[Quick start](README.md) | Prerequisites > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
|
||||
<sup>⚡️[Quick start](quick-start.md) | Prerequisites > [Configuring your DNS settings](configuring-dns.md) > [Getting the playbook](getting-the-playbook.md) > [Configuring the playbook](configuring-playbook.md) > [Installing](installing.md)</sup>
|
||||
|
||||
To install Matrix services using this Ansible playbook, you need to prepare several requirements both on your local computer (where you will run the playbook to configure the server) and the server (where the playbook will install the Matrix services for you). **These requirements need to be set up manually** before proceeding to the next step.
|
||||
|
||||
We will be using `example.com` as the domain in the following instruction. Please remember to replace it with your own domain before running any commands.
|
||||
|
||||
## Your local computer
|
||||
|
||||
- [Ansible](http://ansible.com/) program. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible.
|
||||
|
||||
202
docs/quick-start.md
Normal file
202
docs/quick-start.md
Normal file
@ -0,0 +1,202 @@
|
||||
# Quick start
|
||||
|
||||
<!--
|
||||
NOTE:
|
||||
- Let's keep it as tidy and simple as possible.
|
||||
- Because this documentation is intended to be referred by those who have not configured a Matrix server and services by using the playbook, from the educational point of view it intentionally avoids instructions based on just program's "recipes" in favor of ansible-playbook commands in most cases.
|
||||
-->
|
||||
|
||||
This page explains how to use this Ansible playbook to install Matrix services on your server with a minimal set of core services.
|
||||
|
||||
We will be using `example.com` as the "base domain" in the following instruction.
|
||||
|
||||
By following the instruction on this page, you will set up:
|
||||
|
||||
- **your own Matrix server** on a `matrix.example.com` server, which is configured to present itself as `example.com`
|
||||
- **your user account** like `@user:example.com` on the server
|
||||
- a **self-hosted Matrix client**, [Element Web](configuring-playbook-client-element-web.md) with the default subdomain at `element.example.com`
|
||||
- Matrix delegation, so that your `matrix.example.com` server (presenting itself as `example.com`) can join the Matrix Federation and communicate with any other server in the Matrix network
|
||||
|
||||
Please remember to replace `example.com` with your own domain before running any commands.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Prerequisites](prerequisites.md)</sup>
|
||||
|
||||
At first, **check prerequisites** and prepare for installation by setting up programs [on your own computer](prerequisites.md#your-local-computer) and [your server](prerequisites.md#server). You also need `root` access on your server (a user that could elevate to `root` via `sudo` also works).
|
||||
|
||||
<!--
|
||||
TODO: Add one liners (or instructions, a script, etc.) for easy and consistent installation of required software. See: https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3757
|
||||
-->
|
||||
|
||||
If you encounter an error during installation, please make sure that you have installed and configured programs correctly.
|
||||
|
||||
One of the main reasons of basic errors is using an incompatible version of required software such as Ansible. Take a look at [our guide about Ansible](ansible.md) for more information. In short: installing the latest available version is recommended.
|
||||
|
||||
## Configure your DNS settings
|
||||
|
||||
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Configuring your DNS settings](configuring-dns.md)</sup>
|
||||
|
||||
After installing and configuring prerequisites, you will need to **configure DNS records**.
|
||||
|
||||
To configure Matrix services in the default settings, go to your DNS service provider, and adjust DNS records as below.
|
||||
|
||||
| Type | Host | Priority | Weight | Port | Target |
|
||||
| ----- | ---------------------------- | -------- | ------ | ---- | ---------------------|
|
||||
| A | `matrix` | - | - | - | `matrix-server-IP` |
|
||||
| CNAME | `element` | - | - | - | `matrix.example.com` |
|
||||
|
||||
As the table illustrates, you need to create 2 subdomains (`matrix.example.com` and `element.example.com`) and point both of them to your server's IP address (DNS `A` record or `CNAME` record is fine).
|
||||
|
||||
It might take some time for the DNS records to propagate after creation.
|
||||
|
||||
**💡 Note**: if you are using Cloudflare DNS, make sure to disable the proxy and set all records to "DNS only"
|
||||
|
||||
## Get the playbook
|
||||
|
||||
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Getting the playbook](getting-the-playbook.md)</sup>
|
||||
|
||||
Next, let's **get the playbook's source code**.
|
||||
|
||||
We recommend to do so with [git](https://git-scm.com/) as it enables you to keep it up to date with the latest source code. While it is possible to download the playbook as a ZIP archive, it is not recommended.
|
||||
|
||||
To get the playbook with git, install git on your computer, go to a directory, and run the command:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
|
||||
```
|
||||
|
||||
It will fetch the playbook to a new `matrix-docker-ansible-deploy` directory underneath the directory you are currently in.
|
||||
|
||||
## Configure the playbook
|
||||
|
||||
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Configuring the playbook](configuring-playbook.md)</sup>
|
||||
|
||||
Now that the playbook was fetched, it is time to **configure** it per your needs.
|
||||
|
||||
To install Matrix services with this playbook, you would at least need 2 configuration files.
|
||||
|
||||
For your convenience, we have prepared example files of them ([`vars.yml`](../examples/vars.yml) and [`hosts`](../examples/hosts)).
|
||||
|
||||
To start quickly based on these example files, go into the `matrix-docker-ansible-deploy` directory and follow the instructions below:
|
||||
|
||||
1. Create a directory to hold your configuration: `mkdir -p inventory/host_vars/matrix.example.com` where `example.com` is your "base domain"
|
||||
2. Copy the sample configuration file: `cp examples/vars.yml inventory/host_vars/matrix.example.com/vars.yml`
|
||||
3. Copy the sample inventory hosts file: `cp examples/hosts inventory/hosts`
|
||||
4. Edit the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`)
|
||||
5. Edit the inventory hosts file (`inventory/hosts`)
|
||||
|
||||
Before editing these 2 files, make sure to read explanations on them to understand what needs to be configured.
|
||||
|
||||
**💡 Notes:**
|
||||
- If you are not in control of anything on the base domain, you would need to set additional configuration on `vars.yml`. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) on our FAQ.
|
||||
- Certain configuration decisions (like the base domain configured in `matrix_domain` and homeserver implementation configured in `matrix_homeserver_implementation`) are final. If you make the wrong choice and wish to change it, you'll have to run the Uninstalling step and start over.
|
||||
- Instead of configuring a lot of things all at once, we recommend starting with the basic (default) settings in order to get yourself familiar with how the playbook works. After making sure that everything works as expected, you can add (and remove) advanced settings / features and run the playbook as many times as you wish.
|
||||
|
||||
## Install
|
||||
|
||||
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Installing](installing.md)</sup>
|
||||
|
||||
After editing `vars.yml` and `hosts` files, let's start the **installation** procedure.
|
||||
|
||||
### Update Ansible roles
|
||||
|
||||
Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside.
|
||||
|
||||
To update your playbook directory and all upstream Ansible roles, run:
|
||||
|
||||
- either: `just update`
|
||||
- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
|
||||
|
||||
If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
|
||||
|
||||
### Run installation command
|
||||
|
||||
Then, run the command below to start installation:
|
||||
|
||||
````sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start
|
||||
````
|
||||
|
||||
If you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the command.
|
||||
|
||||
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 the command.
|
||||
|
||||
Wait until the command completes. If it's all green, everything should be running properly.
|
||||
|
||||
## Create your user account
|
||||
|
||||
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Registering users](registering-users.md)</sup>
|
||||
|
||||
As you have configured your brand new server and the client, you need to **create your user account** on your Matrix server.
|
||||
|
||||
To create your user account (as an administrator of the server) via this Ansible playbook, run the command below on your local computer.
|
||||
|
||||
**💡 Notes**:
|
||||
- Make sure to adjust `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
|
||||
- For `YOUR_USERNAME_HERE`, use a plain username like `john`, not your full identifier (`@user:example.com`)
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=yes' --tags=register-user
|
||||
|
||||
# Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
|
||||
```
|
||||
|
||||
<!--
|
||||
NOTE: detailed instruction to add users can be found on docs/registering-users.md and installing.md, which include a note about usage of admin=yes and admin=no variables. In order to keep this guide as reasonably short as possible, let's not repeat the same instruction here.
|
||||
-->
|
||||
|
||||
## Finalize server installation
|
||||
|
||||
<sup>This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Server Delegation](howto-server-delegation.md)</sup>
|
||||
|
||||
Now that you've configured Matrix services and your user account, you need to **finalize the installation process** by [setting up Matrix delegation (redirection)](howto-server-delegation.md), so that your Matrix server (`matrix.example.com`) can present itself as the base domain (`example.com`) in the Matrix network.
|
||||
|
||||
**This is required for federation to work!** Without a proper configuration, your server will effectively not be part of the Matrix network.
|
||||
|
||||
To configure the delegation, you have these two options. Choose one of them according to your situation.
|
||||
|
||||
- If you can afford to point the base domain at the Matrix server, follow the instruction below which guides you into [serving the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server.
|
||||
- Alternatively, if you're using the base domain for other purposes and cannot point it to the Matrix server (and thus cannot "serve the base domain" from it), you most likely need to [manually install well-known files on the base domain's server](configuring-well-known.md#manually-installing-well-known-files-on-the-base-domains-server).
|
||||
|
||||
To have the base domain served from the integrated web server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_static_files_container_labels_base_domain_enabled: true
|
||||
```
|
||||
|
||||
After configuring the playbook, run the command below and wait until it finishes:
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=install-matrix-static-files,start
|
||||
```
|
||||
|
||||
💡 Running the `install-matrix-static-files` playbook tag (as done here) is an optimized version of running [the full setup command](#run-the-installation-command).
|
||||
|
||||
After the command finishes, you can also check whether your server federates with the Matrix network by using the [Federation Tester](https://federationtester.matrix.org/) against your base domain (`example.com`), not the `matrix.example.com` subdomain.
|
||||
|
||||
If you think something is off with the server configuration, feel free to [re-run the full setup command](#run-the-installation-command) any time.
|
||||
|
||||
## Log in to your user account
|
||||
|
||||
Finally, let's make sure that you can log in to the created account with the specified password.
|
||||
|
||||
You should be able to log in to it with your own [Element Web](configuring-playbook-client-element-web.md) client which you have set up at `element.example.com` by running the playbook. Open the URL (`https://element.example.com`) in a web browser and enter your credentials to log in.
|
||||
|
||||
**If you successfully logged in to your account, installing and configuring is complete**🎉
|
||||
|
||||
Come say Hi👋 in our support room - [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting.
|
||||
|
||||
## Things to do next
|
||||
|
||||
Once you get familiar with the playbook, you might probably want to set up additional services such as a bridge on your server.
|
||||
|
||||
As this page intends to be a quick start guide which explains how to start the core Matrix services, it does not cover a topic like how to set them up. Take a look at the list of [things to do next](installing.md#things-to-do-next) to learn more.
|
||||
|
||||
### ⚠️Keep the playbook and services up-to-date
|
||||
|
||||
While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**.
|
||||
|
||||
Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date.
|
||||
|
||||
For more information about upgrading or maintaining services with the playbook, take at look at this page: [Upgrading the Matrix services](maintenance-upgrading-services.md)
|
||||
@ -1,6 +1,6 @@
|
||||
# Registering users
|
||||
|
||||
This documentation page tells you how to create user account on your Matrix server.
|
||||
This documentation page tells you how to create user accounts on your Matrix server.
|
||||
|
||||
Table of contents:
|
||||
|
||||
@ -14,7 +14,10 @@ Table of contents:
|
||||
|
||||
## Registering users manually
|
||||
|
||||
**Note**: in the commands below, `<your-username>` is just a plain username (like `john`), not your full `@<username>:example.com` identifier.
|
||||
**Notes**:
|
||||
- Make sure to adjust `USERNAME_HERE` and `PASSWORD_HERE`
|
||||
- For `USERNAME_HERE`, use a plain username like `john`, not a full identifier (`@user:example.com`)
|
||||
- Use `admin=yes` or `admin=no` depending on whether you wish to make the user an administrator of the Matrix server
|
||||
|
||||
After registering a user (using one of the methods below), **you can log in with that user** via the [Element Web](configuring-playbook-client-element-web.md) service that this playbook has installed for you at a URL like this: `https://element.example.com/`.
|
||||
|
||||
@ -22,10 +25,10 @@ After registering a user (using one of the methods below), **you can log in with
|
||||
|
||||
It's best to register users via the Ansible playbook, because it works regardless of homeserver implementation (Synapse, Dendrite, etc) or usage of [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) (MAS).
|
||||
|
||||
To register a user via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
|
||||
To register a user via this Ansible playbook:
|
||||
|
||||
```sh
|
||||
just register-user <your-username> <your-password> <admin access: yes or no>
|
||||
just register-user USERNAME_HERE PASSWORD_HERE <admin access: yes or no>
|
||||
|
||||
# Example: `just register-user john secret-password yes`
|
||||
```
|
||||
@ -33,11 +36,13 @@ just register-user <your-username> <your-password> <admin access: yes or no>
|
||||
**or** by invoking `ansible-playbook` manually:
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=USERNAME_HERE password=PASSWORD_HERE admin=<yes|no>' --tags=register-user
|
||||
|
||||
# Example: `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user`
|
||||
# Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=john password=secret-password admin=yes' --tags=register-user
|
||||
```
|
||||
|
||||
Feel free to register as many users (for friends, family, etc.) as you want. Still, perhaps you should grant full administrative access to your user account only (with `admin=yes`), and others should be created with `admin=no`.
|
||||
|
||||
⚠️ **Warning**: If you're registering users against Matrix Authentication Service, do note that it [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.
|
||||
|
||||
### Registering users manually for Synapse
|
||||
@ -45,7 +50,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-usern
|
||||
If you're using the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default), you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):
|
||||
|
||||
```sh
|
||||
/matrix/synapse/bin/register-user <your-username> <your-password> <admin access: 0 or 1>
|
||||
/matrix/synapse/bin/register-user USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>
|
||||
|
||||
# Example: `/matrix/synapse/bin/register-user john secret-password 1`
|
||||
```
|
||||
@ -55,7 +60,7 @@ If you're using the [Synapse](configuring-playbook-synapse.md) homeserver implem
|
||||
If you're using the [Dendrite](./configuring-playbook-dendrite.md) homeserver implementation, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):
|
||||
|
||||
```sh
|
||||
/matrix/dendrite/bin/create-account <your-username> <your-password> <admin access: 0 or 1>
|
||||
/matrix/dendrite/bin/create-account USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>
|
||||
|
||||
# Example: `/matrix/dendrite/bin/create-account john secret-password 1`
|
||||
```
|
||||
@ -65,7 +70,7 @@ If you're using the [Dendrite](./configuring-playbook-dendrite.md) homeserver im
|
||||
If you're using the [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) and your existing homeserver (most likely [Synapse](./configuring-playbook-synapse.md)) is delegating authentication to it, you can register users via the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#install-matrix-server-and-services)):
|
||||
|
||||
```sh
|
||||
/matrix/matrix-authentication-service/bin/register-user <your-username> <your-password> <admin access: 0 or 1>
|
||||
/matrix/matrix-authentication-service/bin/register-user USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>
|
||||
|
||||
# Example: `/matrix/matrix-authentication-service/bin/register-user john secret-password 1`
|
||||
```
|
||||
|
||||
@ -2,14 +2,16 @@
|
||||
|
||||
## Option 1 (if you are using the integrated Postgres database):
|
||||
|
||||
You can reset a user's password via the Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
|
||||
**Notes**:
|
||||
- Make sure to adjust `USERNAME_HERE` and `PASSWORD_HERE`
|
||||
- For `USERNAME_HERE`, use a plain username like `john`, not a full identifier (`@user:example.com`)
|
||||
|
||||
You can reset a user's password via the Ansible playbook:
|
||||
|
||||
```
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password>' --tags=update-user-password
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=USERNAME_HERE password=PASSWORD_HERE' --tags=update-user-password
|
||||
```
|
||||
|
||||
**Note**: `<your-username>` is just a plain username (like `john`), not your full `@<username>:example.com` identifier.
|
||||
|
||||
**You can then log in with that user** via Element Web that this playbook has created for you at a URL like this: `https://element.example.com/`.
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user