[discourse-gatekeeper] Migrate charm docs

docs/explanation/charm-architecture.md

@@ -108,4 +108,4 @@ juju config synapse server_name=myserver.myserver.com
 self.framework.observe(self.on.config_changed, self._on_config_changed)
 4. The method `_on_config_changed` will take the necessary actions. 
 The actions include waiting for all the relations to be ready and then configuring
-the containers.
+the containers.

docs/how-to/backup-and-restore.md

@@ -23,7 +23,7 @@ juju config s3-integrator endpoint=<s3 endpoint> bucket=<bucket name> path=<opti
 juju run s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key>
 ```
 
-Integrate with Synapse with:
+Integrate with Synapse using:
 
 `juju integrate synapse:backup s3-integrator`
 
@@ -37,7 +37,7 @@ juju config synapse backup_passphrase=<secret passphase>
 
 ### Create the backup
 
-Create the backup with the next command:
+Create the backup:
 ```
 juju run synapse/leader create-backup
 ```
@@ -53,20 +53,20 @@ juju run synapse/leader list-backups
 ### Back up PostgreSQL
 
 Follow the instructions of the PostgreSQL charm:
- - For [postgresql-k8s](https://charmhub.io/postgresql-k8s/docs/h-create-and-list-backups).
- - For [postgresql](https://charmhub.io/postgresql/docs/h-create-and-list-backups).
+ - For [postgresql-k8s](https://charmhub.io/postgresql-k8s/docs/h-create-backup).
+ - For [postgresql](https://charmhub.io/postgresql/docs/h-create-backup).
 
 If you plan to restore PostgreSQL in a different model or cluster, you will need
 to also back up the cluster passwords. See:
- - For [postgresql-k8s](https://charmhub.io/postgresql-k8s/docs/h-migrate-cluster-via-restore).
- - For [postgresql](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore).
+ - For [postgresql-k8s](https://charmhub.io/postgresql-k8s/docs/h-migrate-cluster).
+ - For [postgresql](https://charmhub.io/postgresql/docs/h-migrate-cluster).
 
 
 ## Restore
 
-The recommendation is to first restore PostgreSQL if necessary. Then deploying,
-configuring and integrating Synapse with other charms as done in a normal deployment
-and finally restoring Synapse. 
+The recommendation is to first restore PostgreSQL if necessary. Then deploy,
+configure and integrate Synapse with other charms as done in a normal deployment.
+Finally, restore Synapse. 
 
 The PostgreSQL and Synapse charm revisions should be the same ones as the ones used
 for the backup. The configuration for Synapse before restoring the backup should also
@@ -78,11 +78,11 @@ the configuration option `server_name` and any other configuration related to th
 
 
 If you use the PostgreSQL integration, follow the instructions given by PostgreSQL:
- - For postgresql-k8s: [local restore](https://charmhub.io/postgresql/docs/h-restore-backup), [foreign backup](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore).
- - for postgresql: [local restore](https://charmhub.io/postgresql/docs/h-restore-backup), [foreign backup](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore).
+ - For postgresql-k8s: [local restore](https://charmhub.io/postgresql/docs/h-restore-backup), [foreign backup](https://charmhub.io/postgresql/docs/h-migrate-cluster).
+ - for postgresql: [local restore](https://charmhub.io/postgresql/docs/h-restore-backup), [foreign backup](https://charmhub.io/postgresql/docs/h-migrate-cluster).
 
 If you used the foreign backup, once the backup for PostgreSQL is restored, you should remove the S3 integration,
-as it was created in a different cluster, by running:
+as it was created in a different cluster:
 
 ```
 juju remove-relation s3-integrator postgresql
@@ -91,7 +91,7 @@ juju remove-relation s3-integrator postgresql
 ### Deploy Synapse
 
 Synapse should be deployed, integrated with all necessary charms and configured. If necessary, Synapse should be integrated with the PostgreSQL charm that
-has already being restored.
+has already been restored.
 
 ### Restore Synapse
 

docs/how-to/horizontally-scale.md

@@ -0,0 +1,86 @@
+# How to horizontally scale
+
+A Synapse deployment can scale horizontally by running multiple Synapse processes called workers.
+While adding more units to the Synapse charm, one of them will be the Main process and others,
+the workers. This architecture has specific requirements that will be described in this document.
+
+For more details about scaling, refer to ["Scaling synapse via workers"](https://element-hq.github.io/synapse/latest/workers.html#scaling-synapse-via-workers) in the Synapse documentation.
+
+## Requirements
+
+- Synapse charm deployed and integrated with PostgreSQL charm.
+
+The tutorial ["Getting started"](https://discourse.charmhub.io/t/synapse-docs-getting-started/12737) can be used to meet this requirement.
+
+## Steps
+
+### Deploy Redis and integrate it with Synapse
+
+Run the following commands.
+
+```
+juju deploy redis-k8s --channel edge
+juju integrate synapse redis
+```
+
+Once the output of the `juju status` command shows that the units are active and idle, proceed with
+the next step.
+
+### Deploy S3-integrator and integrate it with Synapse
+
+This will enable S3 storage provider so media will be stored on a S3 bucket.
+
+Replace the configuration options with your specific configuration. The ones used below should be
+modified to match your environment.
+
+Refer to [s3-integrator](https://charmhub.io/s3-integrator/) for specific configuration options.
+
+```
+juju deploy s3-integrator s3-integrator-media --channel edge
+juju config s3-integrator-media endpoint=http://endpoint bucket=synapse-media-bucket path=/media region=us-east-1 s3-uri-style=path
+juju integrate synapse:media s3-integrator-media
+```
+
+Once the output of the `juju status` command shows that the units are active and idle, proceed with
+the next step.
+
+### Scale Synapse application
+
+With all integrations set, scale Synapse up by running the following command.
+
+```
+juju scale-application synapse 3
+```
+
+### Verify status
+
+The output of `juju status --relations` should look like this now.
+
+```
+$ juju status --relations
+Model             Controller    Cloud/Region         Version  SLA          Timestamp
+prod-synapse-k8s  ctr1          cloud1/default  3.1.8    unsupported  20:04:20Z
+
+SAAS             Status       Store         URL
+postgresql       active       cloud1  admin/prod-chat-synapse-db.postgresql
+
+App                       Version  Status   Scale  Charm                     Channel        Rev  Address        Exposed  Message
+media-s3-integrator                active      1  s3-integrator              latest/stable   13  10.10.10.1     no         
+redis                     7.0.4    active       1  redis-k8s                 latest/edge     27  10.10.10.2     no       
+synapse                            active       3  synapse                   latest/stable  303  10.10.10.3     no       
+
+Unit                         Workload     Agent  Address          Ports  Message      
+media-s3-integrator/0*       active       idle   192.168.1.2         
+redis/0*                     active       idle   192.168.1.7          
+synapse/0                    active       idle   192.168.1.4         
+synapse/1*                   active       idle   192.168.1.8         
+synapse/2                    active       idle   192.168.1.6          
+
+Integration provider                      Requirer                                  Interface            Type     Message 
+media-s3-integrator:s3-credentials        synapse:media                             s3                   regular  
+media-s3-integrator:s3-integrator-peers   media-s3-integrator:s3-integrator-peers   s3-integrator-peers  peer     
+postgresql:database                       synapse:database                          postgresql_client    regular  
+redis:redis                               synapse:redis                             redis                regular  
+redis:redis-peers                         redis:redis-peers                         redis-peers          peer     
+synapse:synapse-peers                     synapse:synapse-peers                     synapse-instance     peer 
+```

docs/index.md

@@ -29,10 +29,12 @@ If there’s a particular area of documentation that you’d like to see that’
   1. [Getting Started](tutorial/getting-started.md)
 1. [How to](how-to)
   1. [Configure SMTP](how-to/configure-smtp.md)
-  2. [Contribute](how-to/contribute.md)
-  3. [Backup and Restore](how-to/backup-and-restore.md)
+  1. [Backup and Restore](how-to/backup-and-restore.md)
+  1. [Contribute](how-to/contribute.md)
+  1. [How to horizontally scale](how-to/horizontally-scale.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)
-  2. [Integrations](reference/integrations.md)
+  1. [External access](reference/external-access.md)
+  1. [Integrations](reference/integrations.md)
 1. [Explanation](explanation)
   1. [Charm architecture](explanation/charm-architecture.md)

docs/reference/external-access.md

@@ -15,4 +15,4 @@ Synapse configuration sets default to matrix.org.
 Federation is the process by which users on different servers can participate in the same room.
 For this to work, the server communicate with each other via HTTPS port 8448 or a different port
 depending how the server is configured. See ["Setting up federation"](https://matrix-org.github.io/synapse/latest/federate.html)
-in Matrix documentation for reference.
+in Matrix documentation for reference.

docs/reference/integrations.md

@@ -117,4 +117,4 @@ is set with the Synapse configuration option `notif_from`.
 For the smtp-integrator, insecure configurations with `transport_security=none` or not
 authenticated connections with `auth_type=none` are not supported.
 
-See more information in [Charm Architecture](https://charmhub.io/synapse/docs/explanation-charm-architecture).
+See more information in [Charm Architecture](https://charmhub.io/synapse/docs/explanation-charm-architecture).

docs/tutorial/getting-started.md

@@ -12,11 +12,11 @@ Synapse instance via Element Desktop application.
 
 ## Requirements
 - Juju 3 installed.
-- Juju controller and model created.
+- Juju controller created.
 
 For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
 
-## Setting up a Tutorial Model
+## Set up a Tutorial Model
 
 To manage resources effectively and to separate this tutorial's workload from
 your usual work, we recommend creating a new model using the following command.
@@ -110,7 +110,7 @@ accordingly:
 10.152.183.225 tutorial-synapse.juju.local
 ```
 
-Optional: run `echo "10.152.183.225 tutorial-synapse.juju.local" >> /etc/hosts`
+> Optional: run `echo "10.152.183.225 tutorial-synapse.juju.local" >> /etc/hosts`
 to redirect the output of the command `echo` to the end of the file `/etc/hosts`.
 
 After that, visit http://tutorial-synapse.juju.local in a browser and you'll be
@@ -139,5 +139,5 @@ Well done! You've successfully completed the Synapse tutorial. To remove the
 model environment you created during this tutorial, use the following command.
 
 ```
-juju destroy model synapse-tutorial -y
+juju destroy-model synapse-tutorial
 ```