Update docs/README.md (#3822 )

* Update docs/README.md: add "installation guides" section Add the emoji to the link to quick-start.md only and not to full installation guide to emphasize the quick start guide Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: move a link to faq.md down Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: add "Maintenance" section Add a hint to join the support room under "Maintenance" header. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: create the "configuration options" section and add a note Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: sort list items Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: emphasize the anchor link to faq.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: add other anchor links to the "other documentation pages" section Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: add the emoji ℹ️ before the anchor link to faq.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: explanation about FAQ Remove the hint to check the installation guides as links to them are listed on top of this page. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/README.md: update text of the anchor link to docs/getting-the-playbook.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Merge pull request #3819 from luixxiul/fix
2025-02-11 17:48:57 +01:00 · 2024-11-25 18:18:11 +02:00 · 2024-11-25 13:57:36 +02:00 · 2024-11-25 20:42:02 +09:00
2 changed files with 85 additions and 38 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -1,49 +1,86 @@
 # Table of Contents

- [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.
+## ⬇️ Installaton guides <!-- NOTE: the 🚀 emoji is used by "Getting started" on README.md -->

- [Quick start](quick-start.md) - follow the guide to set up minimum core services on your server
+There are two installation guides available for beginners and advanced users.

- [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook
+- ⚡ **[Quick start](quick-start.md) (for beginners)**: this is recommended for those who do not have an existing Matrix server and want to start quickly with "opinionated defaults".

- [Configuring your DNS settings](configuring-dns.md)
+- **Full installation guide (for advanced users)**: if you need to import an existing Matrix server's data into the new server or want to learn more while setting up the server, follow this guide.

- [Getting this playbook's source code](getting-the-playbook.md)
+    - [Prerequisites](prerequisites.md)

- [Configuring the playbook](configuring-playbook.md)
+    - [Configuring your DNS settings](configuring-dns.md)

- [Installing](installing.md)
+    - [Getting the playbook](getting-the-playbook.md)

-  - **Importing data from another server installation**
+    - [Configuring the playbook](configuring-playbook.md)

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

-    - [Importing an existing Postgres database (from another installation)](importing-postgres.md) (optional)
+## 🛠️ Configuration options

-    - [Importing `media_store` data files from an existing Synapse installation](importing-synapse-media-store.md) (optional)
+<!--
+NOTE:
+- Avoid putting the same anchor links as configuring-playbook.md lists under the "configuration options" section. Note that most of them are linked to "configure-playbook-*.md" and their titles start with "Setting up" (e.g. "Setting up Hydrogen").
+-->

-  - [Server Delegation](howto-server-delegation.md)
+You can check useful documentation for configuring components here: [Configuring the playbook](configuring-playbook.md)

-    - Server Delegation via a well-known file (recommended): [Installing well-known files on the base domain's server](configuring-well-known.md#installing-well-known-files-on-the-base-domain-s-server)
+- [Administration](configuring-playbook.md#administration) -  services that help you in administrating and monitoring your Matrix installation

-      - [Serving the base domain](configuring-playbook-base-domain-serving.md)
+- [Authentication and user-related](configuring-playbook.md#authentication-and-user-related) - extend and modify how users are authenticated on your homeserver

-    - [Server Delegation via a DNS SRV record (advanced)](howto-srv-server-delegation.md)
+- [Bots](configuring-playbook.md#bots) - bots provide various additional functionality to your installation
+
+- [Bridges](configuring-playbook.md#bridging-other-networks) - bridges can be used to connect your Matrix installation with third-party communication networks
+
+- [Clients](configuring-playbook.md#clients) - web clients for Matrix that you can host on your own domains
+
+- [Core service adjustments](configuring-playbook.md#core-service-adjustments) - backbone of your Matrix system
+
+- [File Storage](configuring-playbook.md#file-storage) - use alternative file storage to the default `media_store` folder
+
+<!-- NOTE: sort list items above alphabetically -->
+
+- [Other specialized services](configuring-playbook.md#other-specialized-services) - various services that don't fit any other categories
+
+## 👨‍🔧 Maintenance
+
+If your server and services experience issues, feel free to come to [our support room](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) and ask for help.
+
+<!-- NOTE: sort list items alphabetically -->
+
+- [Checking if services work](maintenance-checking-services.md)
+
+- [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)
+
+- [PostgreSQL maintenance](maintenance-postgres.md)
+
+- [Synapse maintenance](maintenance-synapse.md)
+
+- [Upgrading services](maintenance-upgrading-services.md)
+
+## Other documentation pages <!-- NOTE: this header's title and the section below need optimization -->
+
+- ℹ️ **[FAQ](faq.md)** - various Frequently Asked Questions about Matrix, with a focus on this Ansible playbook
+
+<!-- NOTE: sort list items under faq.md alphabetically -->
+
+- [Alternative architectures](alternative-architectures.md)
+
+- [Container images used by the playbook](container-images.md)
+
+- [Obtaining an Access Token](obtaining-access-tokens.md)

 - [Playbook tags](playbook-tags.md)

 - [Registering users](registering-users.md)

- [Updating users passwords](updating-users-passwords.md)
+- [Running `just` commands](just.md)

- [Maintenance / checking if services work](maintenance-checking-services.md)
-
- [Maintenance / upgrading services](maintenance-upgrading-services.md)
-
- [Maintenance / Synapse](maintenance-synapse.md)
-
- [Maintenance / PostgreSQL](maintenance-postgres.md)
-
- [Maintenance and Troubleshooting](maintenance-and-troubleshooting.md)
+- [Self-building](self-building.md)

 - [Uninstalling](uninstalling.md)
+
+- [Updating users passwords](updating-users-passwords.md)
--- a/docs/maintenance-upgrading-services.md
+++ b/docs/maintenance-upgrading-services.md
@ -14,27 +14,37 @@ If you want to be notified when new versions of Synapse are released, you should

 ## Steps to upgrade the Matrix services

+### Check the changelog
+
 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 the playbook and the Ansible roles

- update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) using:
+If it looks good to you, go to the `matrix-docker-ansible-deploy` directory, update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) by running:

-  - 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`)
+- 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`
+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`

-  For details about `just` commands, take a look at: [Running `just` commands](just.md).
+**Note**: for details about `just` commands, take a look at: [Running `just` commands](just.md).

- re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services:
+### Re-run the playbook setup

-  ```sh
-  ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
-  ```
+After updating the Ansible roles, then re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services:

-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.
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
+```

-A way to invoke these `ansible-playbook` commands with less typing is to run the `just` "recipe": `just install-all` or `just setup-all`.
+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.

-**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).
+#### Run `just` to execute shortcut command
+
+If you want to invoke the `ansible-playbook` command with less typing, you can run `just` to execute the shortcut command: `just install-all` (or `just setup-all`). Note that it restarts all services automatically.
+
+## PostgreSQL major version upgrade
+
+Major version upgrades to the internal PostgreSQL database are not done automatically. Upgrades must be performed manually.
+
+For details about upgrading it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).