matrix-docker-ansible-deploy/docs/installing.md

# Installing

## 1. Installing the Matrix services

If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playbook.md), you can start the installation procedure.

Run this command to install the Matrix services:

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

The above command **doesn't start any services just yet** (another step does this later - below). Feel free to **re-run this setup command any time** you think something is off with the server configuration.

**Notes**:
- if you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the above (and all other) Ansible commands.
- if you **do** use SSH keys for authentication, **and** use a non-root user to *become* root (sudo), you may need to add `-K` (`--ask-become-pass`) to the above (and all other) Ansible commands.


## 2. Things you might want to do after installing

**Before starting the services**, you may want to do additional things like:

- [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)

- [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)

- [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)


## 3. Starting the services

When you're ready to start the Matrix services (and set them up to auto-start in the future), run this command:

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

## 4. Finalize the installation

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


## 5. Things to do next

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

- [check if services work](maintenance-checking-services.md)
- or [create your first Matrix user account](registering-users.md)
- or [set up additional services](configuring-playbook.md#other-configuration-options) (bridges to other chat networks, bots, etc.)
- or learn how to [upgrade services when new versions are released](maintenance-upgrading-services.md)
- or learn how to [maintain your server](faq.md#maintenance)
- or join some Matrix rooms:
  * via the *Explore rooms* feature in Element or some other client, or by discovering them using this [matrix-static list](https://view.matrix.org). Note: joining large rooms may overload small servers.
  * or 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.
- or help make this playbook better by contributing (code, documentation, or [coffee/beer](https://liberapay.com/s.pantaleev/donate))
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00			`# Installing`

Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`## 1. Installing the Matrix services`

Update installing.md 2018-09-08 21:23:34 +00:00			`If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playbook.md), you can start the installation procedure.`
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00
Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`Run this command to install the Matrix services:`
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00
			```bash
			`ansible-playbook -i inventory/hosts setup.yml --tags=setup-all`
			```

Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`The above command doesn't start any services just yet (another step does this later - below). Feel free to re-run this setup command any time you think something is off with the server configuration.`
Add note about ask-become-pass This flag is necessary for Ansible to ask for the sudo password when using the non-root option as documented in the `hosts` file. Otherwise, Ansible errors out with `missing sudo password`. 2020-05-09 18:04:49 +00:00
Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`Notes:`
			- if you don't use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the above (and all other) Ansible commands.
			- if you do use SSH keys for authentication, and use a non-root user to become root (sudo), you may need to add `-K` (`--ask-become-pass`) to the above (and all other) Ansible commands.
Add a note for users not using SSH keys 2020-01-18 17:55:26 +00:00
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00
Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`## 2. Things you might want to do after installing`
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00
Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`Before starting the services, you may want to do additional things like:`
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00
Rename some doc files and commands related to importing Since we'll likely have generic SQLite database importing via [pgloader](https://pgloader.io/) for migrating bridge databases from SQLite to Postgres, we'd rather avoid calling the "import Synapse SQLite database" command as just `--tags=import-sqlite-db`. Similarly, for the media store, we'd like to mention that it's related to Synapse as well. We'd like to be more explicit, so as to be less confusing, especially in light of other homeserver implementations coming in the future. 2020-12-13 23:48:36 +00:00			`- [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional)`
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00
Add support for importing an existing Postgres database 2019-01-01 12:40:48 +00:00			`- [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)`

Rename some doc files and commands related to importing Since we'll likely have generic SQLite database importing via [pgloader](https://pgloader.io/) for migrating bridge databases from SQLite to Postgres, we'd rather avoid calling the "import Synapse SQLite database" command as just `--tags=import-sqlite-db`. Similarly, for the media store, we'd like to mention that it's related to Synapse as well. We'd like to be more explicit, so as to be less confusing, especially in light of other homeserver implementations coming in the future. 2020-12-13 23:48:36 +00:00			- [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00

Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`## 3. Starting the services`
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00
Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`When you're ready to start the Matrix services (and set them up to auto-start in the future), run this command:`
Split README into a bunch of files in docs/ 2018-08-08 07:07:02 +00:00
			```bash
			`ansible-playbook -i inventory/hosts setup.yml --tags=start`
			```

Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`## 4. Finalize the installation`

			`Now that services are running, you need to finalize the installation process (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md).`
Improve "things to do after installation" docs section 2021-01-26 15:19:28 +00:00

Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`## 5. Things to do next`
Improve "things to do after installation" docs section 2021-01-26 15:19:28 +00:00
Update installing.md to be a bit more clear This change should make it more obvious which order the steps must be done 2021-10-20 03:57:01 +00:00			`After you have started the services and finalized the installation process (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md), you can:`
Improve "things to do after installation" docs section 2021-01-26 15:19:28 +00:00
			`- [check if services work](maintenance-checking-services.md)`
			`- or [create your first Matrix user account](registering-users.md)`
			`- or [set up additional services](configuring-playbook.md#other-configuration-options) (bridges to other chat networks, bots, etc.)`
			`- or learn how to [upgrade services when new versions are released](maintenance-upgrading-services.md)`
			`- or learn how to [maintain your server](faq.md#maintenance)`
			`- or join some Matrix rooms:`
			`* via the Explore rooms feature in Element or some other client, or by discovering them using this [matrix-static list](https://view.matrix.org). Note: joining large rooms may overload small servers.`
			`* or 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.`
			`- or help make this playbook better by contributing (code, documentation, or [coffee/beer](https://liberapay.com/s.pantaleev/donate))`