@ -12,7 +12,7 @@ Using this playbook, you can get the following services configured on your serve
- (optional) [Amazon S3](https://aws.amazon.com/s3/) storage for your Matrix Synapse's content repository (`media_store`) files using [Goofys](https://github.com/kahing/goofys)
- (optional default) [PostgreSQL](https://www.postgresql.org/) database for Matrix Synapse - providing better performance than the default [SQLite](https://sqlite.org/) database. Using an external PostgreSQL server [is possible](#using-an-external-postgresql-server-optional) as well
- (optional default) [PostgreSQL](https://www.postgresql.org/) database for Matrix Synapse. [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) is also possible.
- a [STUN/TURN server](https://github.com/coturn/coturn) for WebRTC audio/video calls
@ -29,15 +29,15 @@ Basically, this playbook aims to get you up-and-running with all the basic neces
This is similar to the [EMnify/matrix-synapse-auto-deploy](https://github.com/EMnify/matrix-synapse-auto-deploy) Ansible deployment, but:
- this one is a complete Ansible playbook (instead of just a role), so it should be**easier to run** - especially for folks not familiar with Ansible
- this one is a complete Ansible playbook (instead of just a role), so it's**easier to run** - especially for folks not familiar with Ansible
- this one **can be re-ran many times** without causing trouble
- works on both **CentOS** (7.0+) and Debian-based distributions (**Debian** 9/Stretch+, **Ubuntu** 16.04+)
- this one keeps mostly everything in a single directory (`/matrix` by default) and **doesn't "contaminate" your server** with files all over the place
- this one installs everything in a single directory (`/matrix` by default) and **doesn't "contaminate" your server** with files all over the place
- this one **doesn't necessarily take over** ports 80 and 443. By default, it sets up nginx for you there, but you can disable that and configure your own webserver (proxy)
- this one **doesn't necessarily take over** ports 80 and 443. By default, it sets up nginx for you there, but you can also [use your own webserver](docs/configuring-playbook-own-webserver.md)
- this one **runs everything in Docker containers**, so it's likely more predictable and less fragile (see [Docker images used by this playbook](#docker-images-used-by-this-playbook))
@ -48,252 +48,16 @@ This is similar to the [EMnify/matrix-synapse-auto-deploy](https://github.com/EM
- this one optionally **allows you to use an external PostgreSQL server** for Matrix Synapse's database (but defaults to running one in a container)
## Prerequisites
## Installation
- **CentOS** (7.0+), **Debian** (9/Stretch+) or **Ubuntu** (16.04+) server. This playbook can take over your whole server or co-exist with other services that you have there.
To configure and install Matrix on your own server, follow the [README in the docs/ directory](docs/README.md).
- [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python`).
- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you
## Changes
- properly configured DNS SRV record for `<your-domain>` (details in [Configuring DNS](#configuring-dns) below)
This playbook evolves over time, sometimes with backward-incompatible changes.
- `matrix.<your-domain>` domain name pointing to your new server - this is where the Matrix Synapse server will live (details in [Configuring DNS](#configuring-dns) below)
- `riot.<your-domain>` domain name pointing to your new server - this is where the Riot web UI will live (details in [Configuring DNS](#configuring-dns) below)
- some TCP/UDP ports open. This playbook configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports: `80/tcp` (HTTP webserver), `443/tcp` (HTTPS webserver), `3478/tcp` (STUN over TCP), `3478/udp` (STUN over UDP), `8448/tcp` (Matrix federation HTTPS webserver), `49152-49172/udp` (TURN over UDP).
## Configuring DNS
In order to use an identifier like `@<username>:<your-domain>`, you don't actually need
to install anything on the actual `<your-domain>` server.
All services created by this playbook are meant to be installed on their own server (such as `matrix.<your-domain>`).
In order to do this, you must first instruct the Matrix network of this by setting up a DNS SRV record (think of it as a "redirect").
The SRV record should look like this:
- Name: `_matrix._tcp` (use this text as-is)
- Content: `10 0 8448 matrix.<your-domain>` (replace `<your-domain>` with your own)
Once you've set up this DNS SRV record, you should create 2 other domain names (`matrix.<your-domain>` and `riot.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` is fine).
This playbook can then install all the services on that new server and you'll be able to join the Matrix network as `@<username>:<your-domain>`, even though everything is installed elsewhere (not on `<your-domain>`).
## Configuration
Once you have your server and you have [configured your DNS records](#configuring-dns), you can proceed with configuring this playbook, so that it knows what to install and where.
You can follow these steps:
- create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
- copy the sample configuration file (`cp examples/host-vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
- edit the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to your liking. You may also take a look at `roles/matrix-server/defaults.main.yml` and see if there's something you'd like to copy over and override in your `vars.yml` configuration file.
- copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
- edit the inventory hosts file (`inventory/hosts`) to your liking
## Amazon S3 configuration (optional)
By default, this playbook configures your server to store Matrix Synapse's content repository (`media_store`) files on the local filesystem.
If that's alright, you can skip ahead.
If you'd like to store Matrix Synapse's content repository (`media_store`) files on Amazon S3,
you can let this playbook configure [Goofys](https://github.com/kahing/goofys) for you.
You'll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example security policy:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1400105486000",
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::your-bucket-name",
"arn:aws:s3:::your-bucket-name/*"
]
}
]
}
```
You then need to enable S3 support in your configuration file (`inventory/matrix.<your-domain>/vars.yml`).
The database (as specified in `matrix_postgres_db_name`) must exist and be accessible with the given credentials.
It must be empty or contain a valid Matrix Synapse database. If empty, Matrix Synapse would populate it the first time it runs.
## Using your own webserver, instead of this playbook's nginx proxy (optional)
By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
If that's alright, you can skip ahead.
If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.
All it takes is editing your configuration file (`inventory/matrix.<your-domain>/vars.yml`):
```
matrix_nginx_proxy_enabled: false
```
**Note**: even if you do this, in order [to install](#installing), this playbook still expects port 80 to be available. **Please manually stop your other webserver while installing**. You can start it back again afterwards.
**If your own webserver is nginx**, you can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`
**If your own webserver is not nginx**, you can still take a look at the sample files in `/matrix/nginx-proxy/conf.d`, and:
- ensure you set up (separate) vhosts that proxy for both Riot (`localhost:8765`) and Matrix Synapse (`localhost:8008`)
- ensure that the `/.well-known/acme-challenge` location for each "port=80 vhost" is an alias to the `/matrix/ssl/run/acme-challenge` directory (for automated SSL renewal to work)
- ensure that you restart/reload your webserver once in a while, so that renewed SSL certificates would take effect (once a month should be enough)
## Installing
Once you have your server and you have [configured your DNS records](#configuring-dns), you can proceed with installing.
To make use of this playbook, you should invoke the `setup.yml` playbook multiple times, with different tags.
### Configuring a server
Run this as-is to set up a server.
This doesn't start any services just yet (another step does this later - below).
Feel free to re-run this any time you think something is off with the server configuration.
**Note**: `<local-path-to-homeserver.db>` must be a file path to a `homeserver.db` file on your local machine (not on the server!). This file is copied to the server and imported.
### Restoring `media_store` data files from an existing installation
Run this if you'd like to import your `media_store` files from a previous installation of Matrix Synapse.
Run this command (make sure to replace `<local-path-to-media_store>` with a path on your local machine):
**Note**: `<local-path-to-media_store>` must be a file path to a `media_store` directory on your local machine (not on the server!). This directory's contents are then copied to the server.
### Starting the services
Run this as-is to start all the services and to ensure they'll run on system startup later on.
**The old Postgres data directory is backed up** (by renaming to `/matrix/postgres-auto-upgrade-backup`).
It stays around forever, until you **manually decide to delete it**.
As part of the upgrade, the database is dumped to `/tmp`, upgraded and then restored from that dump.
To use a different directory, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"`
**ONLY one database is migrated** (the one specified in `matrix_postgres_db_name`, named `homeserver` by default).
If you've created other databases in that database instance (something this playbook never does and never advises), data will be lost.
## Uninstalling
**Note**: If you have some trouble with your installation configuration, you can just re-run the playbook and it will try to set things up again. You don't need to uninstall and install fresh.
However, if you've installed this on some server where you have other stuff you wish to preserve, and now want get rid of Matrix, it's enough to do these:
- ensure all Matrix services are stopped (`systemctl stop 'matrix*'`)
- delete the Matrix-related systemd .service files (`rm -f /etc/systemd/system/matrix*`) and reload systemd (`systemctl daemon-reload`)
- delete all Matrix-related cronjobs (`rm -f /etc/cron.d/matrix*`)
- delete some helper scripts (`rm -f /usr/local/bin/matrix*`)
- delete some cached Docker images (or just delete them all: `docker rmi $(docker images -aq)`)
- uninstall Docker itself, if necessary
- delete the `/matrix` directory (`rm -rf /matrix`)
When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up with what's new.
To set up Matrix on your domain, you'd need to do some DNS configuration.
To use an identifier like `@<username>:<your-domain>`, you don't actually need
to install anything on the actual `<your-domain>` server.
All services created by this playbook are meant to be installed on their own server (such as `matrix.<your-domain>`).
To accomplish such a "redirect", you need to instruct the Matrix network of this by setting up a DNS SRV record.
The SRV record should look like this:
- Name: `_matrix._tcp` (use this text as-is)
- Content: `10 0 8448 matrix.<your-domain>` (replace `<your-domain>` with your own)
Once you've set up this DNS SRV record, you should create 2 other domain names (`matrix.<your-domain>` and `riot.<your-domain>`) and point both of them to your new server's IP address (DNS `A` record or `CNAME` is fine).
This playbook can then install all the services on that new server and you'll be able to join the Matrix network as `@<username>:<your-domain>`, even though everything is installed elsewhere (not on `<your-domain>`).
When ready to proceed, continue with [Configuring this Ansible playbook](configuring-playbook.md).
# Using your own webserver, instead of this playbook's nginx proxy (optional)
By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
If that's alright, you can skip this.
If you don't want this playbook's nginx webserver to take over your server's 80/443 ports like that,
and you'd like to use your own webserver (be it nginx, Apache, Varnish Cache, etc.), you can.
All it takes is editing your configuration file (`inventory/matrix.<your-domain>/vars.yml`):
```
matrix_nginx_proxy_enabled: false
```
**Note**: even if you do this, in order [to install](#installing), this playbook still expects port 80 to be available. **Please manually stop your other webserver while installing**. You can start it back again afterwards.
**If your own webserver is nginx**, you can most likely directly use the config files installed by this playbook at: `/matrix/nginx-proxy/conf.d`. Just include them in your `nginx.conf` like this: `include /matrix/nginx-proxy/conf.d/*.conf;`
**If your own webserver is not nginx**, you can still take a look at the sample files in `/matrix/nginx-proxy/conf.d`, and:
- ensure you set up (separate) vhosts that proxy for both Riot (`localhost:8765`) and Matrix Synapse (`localhost:8008`)
- ensure that the `/.well-known/acme-challenge` location for each "port=80 vhost" is an alias to the `/matrix/ssl/run/acme-challenge` directory (for automated SSL renewal to work)
- ensure that you restart/reload your webserver once in a while, so that renewed SSL certificates would take effect (once a month should be enough)
Once you have your server and you have [configured your DNS records](configuring-dns.md#configuring-dns), you can proceed with configuring this playbook, so that it knows what to install and where.
You can follow these steps:
- create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
- copy the sample configuration file (`cp examples/host-vars.yml inventory/host_vars/matrix.<your-domain>/vars.yml`)
- edit the configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`) to your liking. You may also take a look at `roles/matrix-server/defaults.main.yml` and see if there's something you'd like to copy over and override in your `vars.yml` configuration file.
- copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
- edit the inventory hosts file (`inventory/hosts`) to your liking
For a basic Matrix installation, that's all you need.
For a more custom setup, see the [Other configuration options](#other-configuration-options) below.
When you're done with all the configuration you'd like to do, continue with [Installing](installing.md).
**Note**: `<local-path-to-homeserver.db>` must be a file path to a `homeserver.db` file on your local machine (not on the server!). This file is copied to the server and imported.
If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playook.md), you can start the installation procedure.
This playbook not only installs the various Matrix services for you, but can also upgrade them as new versions are made available.
To upgrade the services:
- update your playbook directory (`git pull`), so you'd obtain everything new we've done
- take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incomptabile changes that you need to take care of
- re-run the [playbook setup](installing.md): `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all`
- restart the services: `ansible-playbook -i inventory/hosts setup.yml --tags=start`
**Note**: major version upgrades are not done to the internal PostgreSQL database. To upgrade that one, refer to the [upgrading PostgreSQL document](maintenance-upgrading-postgres.md).
- **CentOS** (7.0+), **Debian** (9/Stretch+) or **Ubuntu** (16.04+) server. This playbook can take over your whole server or co-exist with other services that you have there.
- [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python`).
- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you
- properly configured DNS SRV record for `<your-domain>` (details in [Configuring DNS](configuring-dns.md#configuring-dns) below)
- `matrix.<your-domain>` domain name pointing to your new server - this is where the Matrix Synapse server will live (details in [Configuring DNS](configuring-dns.md#configuring-dns) below)
- `riot.<your-domain>` domain name pointing to your new server - this is where the Riot web UI will live (details in [Configuring DNS](configuring-dns.md#configuring-dns) below)
- some TCP/UDP ports open. This playbook configures the server's internal firewall for you. In most cases, you don't need to do anything special. But **if your server is running behind another firewall**, you'd need to open these ports: `80/tcp` (HTTP webserver), `443/tcp` (HTTPS webserver), `3478/tcp` (STUN over TCP), `3478/udp` (STUN over UDP), `8448/tcp` (Matrix federation HTTPS webserver), `49152-49172/udp` (TURN over UDP).
When ready to proceed, continue with [Configuring DNS](configuring-dns.md).
**Note**: `<local-path-to-media_store>` must be a file path to a `media_store` directory on your local machine (not on the server!). This directory's contents are then copied to the server.
**Note**: If you have some trouble with your installation configuration, you can just [re-run the playbook](installing.md) and it will try to set things up again. You don't need to uninstall and install fresh.
However, if you've installed this on some server where you have other stuff you wish to preserve, and now want get rid of Matrix, it's enough to do these:
- ensure all Matrix services are stopped (`systemctl stop 'matrix*'`)
- delete the Matrix-related systemd .service files (`rm -f /etc/systemd/system/matrix*`) and reload systemd (`systemctl daemon-reload`)
- delete all Matrix-related cronjobs (`rm -f /etc/cron.d/matrix*`)
- delete some helper scripts (`rm -f /usr/local/bin/matrix*`)
- delete some cached Docker images (or just delete them all: `docker rmi $(docker images -aq)`)
- delete the Docker network: `docker network rm matrix`
- uninstall Docker itself, if necessary
- delete the `/matrix` directory (`rm -rf /matrix`)
Slavi Pantaleev
6 years ago