From 30c53cdea2055bf2ab6e7727a0a12295d9ba9eab Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Wed, 8 Aug 2018 10:07:02 +0300 Subject: [PATCH] Split README into a bunch of files in docs/ --- README.md | 254 +----------------- docs/README.md | 17 ++ docs/configuring-dns.md | 19 ++ .../configuring-playbook-external-postgres.md | 18 ++ docs/configuring-playbook-own-webserver.md | 25 ++ docs/configuring-playbook-s3.md | 39 +++ docs/configuring-playbook.md | 30 +++ docs/importing-sqlite.md | 15 ++ docs/installing.md | 33 +++ docs/maintenance-upgrading-postgres.md | 20 ++ docs/maintenance-upgrading-services.md | 15 ++ docs/prerequisites.md | 17 ++ docs/registering-users.md | 13 + docs/restoring-media-store.md | 9 + docs/uninstalling.md | 21 ++ 15 files changed, 300 insertions(+), 245 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/configuring-dns.md create mode 100644 docs/configuring-playbook-external-postgres.md create mode 100644 docs/configuring-playbook-own-webserver.md create mode 100644 docs/configuring-playbook-s3.md create mode 100644 docs/configuring-playbook.md create mode 100644 docs/importing-sqlite.md create mode 100644 docs/installing.md create mode 100644 docs/maintenance-upgrading-postgres.md create mode 100644 docs/maintenance-upgrading-services.md create mode 100644 docs/prerequisites.md create mode 100644 docs/registering-users.md create mode 100644 docs/restoring-media-store.md create mode 100644 docs/uninstalling.md diff --git a/README.md b/README.md index da4a4a2b..6ce36ecc 100644 --- a/README.md +++ b/README.md @@ -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 `` (details in [Configuring DNS](#configuring-dns) below) +This playbook evolves over time, sometimes with backward-incompatible changes. -- `matrix.` domain name pointing to your new server - this is where the Matrix Synapse server will live (details in [Configuring DNS](#configuring-dns) below) - -- `riot.` 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 `@:`, you don't actually need -to install anything on the actual `` server. - -All services created by this playbook are meant to be installed on their own server (such as `matrix.`). - -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.` (replace `` with your own) - -Once you've set up this DNS SRV record, you should create 2 other domain names (`matrix.` and `riot.`) 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 `@:`, even though everything is installed elsewhere (not on ``). - - -## 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.`) - -- copy the sample configuration file (`cp examples/host-vars.yml inventory/host_vars/matrix./vars.yml`) - -- edit the configuration file (`inventory/host_vars/matrix./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./vars.yml`). -It would be something like this: - -```yaml -matrix_s3_media_store_enabled: true -matrix_s3_media_store_bucket_name: "your-bucket-name" -matrix_s3_media_store_aws_access_key: "access-key-goes-here" -matrix_s3_media_store_aws_secret_key: "secret-key-goes-here" -matrix_s3_media_store_region: "eu-central-1" -``` - - -## Using an external PostgreSQL server (optional) - -By default, this playbook would set up a PostgreSQL database server on your machine, running in a Docker container. -If that's alright, you can skip ahead. - -If you'd like to use an external PostgreSQL server that you manage, you can edit your configuration file (`inventory/matrix./vars.yml`). -It should be something like this: - -```yaml -matrix_postgres_use_external: true -matrix_postgres_connection_hostname: "your-postgres-server-hostname" -matrix_postgres_connection_username: "your-postgres-server-username" -matrix_postgres_connection_password: "your-postgres-server-password" -matrix_postgres_db_name: "your-postgres-server-database-name" -``` - -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./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. - - ansible-playbook -i inventory/hosts setup.yml --tags=setup-all - - -### Restoring an existing SQLite database (from another installation) - -Run this if you'd like to import your database from a previous default installation of Matrix Synapse. -(don't forget to import your `media_store` files as well - see below). - -While this playbook always sets up PostgreSQL, by default a Matrix Synapse installation would run -using an SQLite database. - -If you have such a Matrix Synapse setup and wish to migrate it here (and over to PostgreSQL), this command is for you. - -Run this command (make sure to replace `` with a file path on your local machine): - - ansible-playbook -i inventory/hosts setup.yml --extra-vars='local_path_homeserver_db=' --tags=import-sqlite-db - -**Note**: `` 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 `` with a path on your local machine): - - ansible-playbook -i inventory/hosts setup.yml --extra-vars='local_path_media_store=' --tags=import-media-store - -**Note**: `` 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. - - ansible-playbook -i inventory/hosts setup.yml --tags=start - - -### Registering a user - -Run this to create a new user account on your Matrix server. - -You can do it via this Ansible playbook (make sure to edit the `` and `` part below): - - ansible-playbook -i inventory/hosts setup.yml --extra-vars='username= password= admin=' --tags=register-user - -**or** using the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)): - - /usr/local/bin/matrix-synapse-register-user - -**Note**: `` is just a plain username (like `john`), not your full `@:` identifier. - - -### Upgrading Postgres - -If you're not using an external Postgres server, this playbook initially installs Postgres for you. - -Once installed like that, this playbook attempts to preserve the Postgres version it starts with. -This is because newer Postgres versions cannot start with data generated by an older Postgres version. -An upgrade must be performed. - -This playbook can upgrade your existing Postgres setup with the following command: - - ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres - -**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. ## Docker images used by this playbook diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..621644b5 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,17 @@ +# Table of Contents + +- [Prerequisites](prerequisites.md) + +- [Configuring your DNS server](configuring-dns.md) + +- [Configuring this Ansible playbook](configuring-playbook.md) + +- [Installing](installing.md) + +- [Registering users](registering-users.md) + +- [Maintenance / upgrading services](maintenance-upgrading-services.md) + +- [Maintenance / upgrading PostgreSQL](maintenance-upgrading-postgres.md) + +- [Uninstalling](uninstalling.md) \ No newline at end of file diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md new file mode 100644 index 00000000..8d9d60a1 --- /dev/null +++ b/docs/configuring-dns.md @@ -0,0 +1,19 @@ +# Configuring your DNS server + +To set up Matrix on your domain, you'd need to do some DNS configuration. + +To use an identifier like `@:`, you don't actually need +to install anything on the actual `` server. + +All services created by this playbook are meant to be installed on their own server (such as `matrix.`). + +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.` (replace `` with your own) + +Once you've set up this DNS SRV record, you should create 2 other domain names (`matrix.` and `riot.`) 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 `@:`, even though everything is installed elsewhere (not on ``). + +When ready to proceed, continue with [Configuring this Ansible playbook](configuring-playbook.md). \ No newline at end of file diff --git a/docs/configuring-playbook-external-postgres.md b/docs/configuring-playbook-external-postgres.md new file mode 100644 index 00000000..2c93ebc3 --- /dev/null +++ b/docs/configuring-playbook-external-postgres.md @@ -0,0 +1,18 @@ +# Using an external PostgreSQL server (optional) + +By default, this playbook would set up a PostgreSQL database server on your machine, running in a Docker container. +If that's alright, you can skip this. + +If you'd like to use an external PostgreSQL server that you manage, you can edit your configuration file (`inventory/matrix./vars.yml`). +It should be something like this: + +```yaml +matrix_postgres_use_external: true +matrix_postgres_connection_hostname: "your-postgres-server-hostname" +matrix_postgres_connection_username: "your-postgres-server-username" +matrix_postgres_connection_password: "your-postgres-server-password" +matrix_postgres_db_name: "your-postgres-server-database-name" +``` + +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. \ No newline at end of file diff --git a/docs/configuring-playbook-own-webserver.md b/docs/configuring-playbook-own-webserver.md new file mode 100644 index 00000000..ba6d8938 --- /dev/null +++ b/docs/configuring-playbook-own-webserver.md @@ -0,0 +1,25 @@ +# 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./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) \ No newline at end of file diff --git a/docs/configuring-playbook-s3.md b/docs/configuring-playbook-s3.md new file mode 100644 index 00000000..ceb3bd13 --- /dev/null +++ b/docs/configuring-playbook-s3.md @@ -0,0 +1,39 @@ +# 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 this. + +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./vars.yml`). +It would be something like this: + +```yaml +matrix_s3_media_store_enabled: true +matrix_s3_media_store_bucket_name: "your-bucket-name" +matrix_s3_media_store_aws_access_key: "access-key-goes-here" +matrix_s3_media_store_aws_secret_key: "secret-key-goes-here" +matrix_s3_media_store_region: "eu-central-1" +``` \ No newline at end of file diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md new file mode 100644 index 00000000..19ff357d --- /dev/null +++ b/docs/configuring-playbook.md @@ -0,0 +1,30 @@ +# Configuration the Ansible playbook + +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.`) + +- copy the sample configuration file (`cp examples/host-vars.yml inventory/host_vars/matrix./vars.yml`) + +- edit the configuration file (`inventory/host_vars/matrix./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). + + +## Other configuration options + +- [Amazon S3 configuration](configuring-playbook-s3.md) (optional) + +- [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) (optional) + +- [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional) \ No newline at end of file diff --git a/docs/importing-sqlite.md b/docs/importing-sqlite.md new file mode 100644 index 00000000..1ae66623 --- /dev/null +++ b/docs/importing-sqlite.md @@ -0,0 +1,15 @@ +# Importing an existing SQLite database from another installation (optional) + +Run this if you'd like to import your database from a previous default installation of Matrix Synapse. +(don't forget to import your `media_store` files as well - see below). + +While this playbook always sets up PostgreSQL, by default a Matrix Synapse installation would run +using an SQLite database. + +If you have such a Matrix Synapse setup and wish to migrate it here (and over to PostgreSQL), this command is for you. + +Run this command (make sure to replace `` with a file path on your local machine): + + ansible-playbook -i inventory/hosts setup.yml --extra-vars='local_path_homeserver_db=' --tags=import-sqlite-db + +**Note**: `` 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. \ No newline at end of file diff --git a/docs/installing.md b/docs/installing.md new file mode 100644 index 00000000..e6a33f6f --- /dev/null +++ b/docs/installing.md @@ -0,0 +1,33 @@ +# Installing + +If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playook.md), you can start the installation procedure. + +Run this as-is to set up a server: + +```bash +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all +``` + +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. + + +# Things you might want to do after installing + +After installing, but before starting the services, you may want to do additional things like: + +- [Importing an existing SQLite database (from another installation)](importing-sqlite.md) (optional) + +- [Restoring `media_store` data files from an existing installation](restoring-media-store.md) (optional) + + +# Starting the services + +When you're ready to start the Matrix services (and set them up to auto-start in the future): + +```bash +ansible-playbook -i inventory/hosts setup.yml --tags=start +``` + +Now that the services are running, you might want to [create your first user account](registering-users.md) \ No newline at end of file diff --git a/docs/maintenance-upgrading-postgres.md b/docs/maintenance-upgrading-postgres.md new file mode 100644 index 00000000..6e6a1b3b --- /dev/null +++ b/docs/maintenance-upgrading-postgres.md @@ -0,0 +1,20 @@ +# Upgrading PostgreSQL + +If you're not using an external Postgres server, this playbook initially installs Postgres for you. + +Once installed like that, this playbook attempts to preserve the Postgres version it starts with. +This is because newer Postgres versions cannot start with data generated by an older Postgres version. +An upgrade must be performed. + +This playbook can upgrade your existing Postgres setup with the following command: + + ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres + +**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. \ No newline at end of file diff --git a/docs/maintenance-upgrading-services.md b/docs/maintenance-upgrading-services.md new file mode 100644 index 00000000..9190f61b --- /dev/null +++ b/docs/maintenance-upgrading-services.md @@ -0,0 +1,15 @@ +# Upgrading the Matrix services + +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). \ No newline at end of file diff --git a/docs/prerequisites.md b/docs/prerequisites.md new file mode 100644 index 00000000..2b5a90bc --- /dev/null +++ b/docs/prerequisites.md @@ -0,0 +1,17 @@ +# Prerequisites + +- **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 `` (details in [Configuring DNS](configuring-dns.md#configuring-dns) below) + +- `matrix.` 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.` 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). \ No newline at end of file diff --git a/docs/registering-users.md b/docs/registering-users.md new file mode 100644 index 00000000..99105285 --- /dev/null +++ b/docs/registering-users.md @@ -0,0 +1,13 @@ +# Registering users + +Run this to create a new user account on your Matrix server. + +You can do it via this Ansible playbook (make sure to edit the `` and `` part below): + + ansible-playbook -i inventory/hosts setup.yml --extra-vars='username= password= admin=' --tags=register-user + +**or** using the command-line after **SSH**-ing to your server (requires that [all services have been started](#starting-the-services)): + + /usr/local/bin/matrix-synapse-register-user + +**Note**: `` is just a plain username (like `john`), not your full `@:` identifier. \ No newline at end of file diff --git a/docs/restoring-media-store.md b/docs/restoring-media-store.md new file mode 100644 index 00000000..62bddcd9 --- /dev/null +++ b/docs/restoring-media-store.md @@ -0,0 +1,9 @@ +# Restoring `media_store` data files from an existing installation (optional) + +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 `` with a path on your local machine): + + ansible-playbook -i inventory/hosts setup.yml --extra-vars='local_path_media_store=' --tags=import-media-store + +**Note**: `` 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. \ No newline at end of file diff --git a/docs/uninstalling.md b/docs/uninstalling.md new file mode 100644 index 00000000..3693ac1b --- /dev/null +++ b/docs/uninstalling.md @@ -0,0 +1,21 @@ +# Uninstalling + +**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`) \ No newline at end of file