modified: docs/index.md // new: docs/reference/actions.md,docs/how-to…

…/contribute.md,docs/reference/integrations.md,docs/explanation/charm-architecture.md,docs/tutorial/getting-started.md

docs/explanation/charm-architecture.md

@@ -0,0 +1,106 @@
+# Charm architecture
+
+Synapse is a drop in replacement for other chat servers like Mattermost and
+Slack. It integrates with [PostgreSQL](https://www.postgresql.org/) as its
+database.
+
+The charm design leverages the [sidecar](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/#example-1-sidecar-containers) pattern to allow multiple containers in each pod
+with [Pebble](https://juju.is/docs/sdk/pebble) running as the workload
+container’s entrypoint.
+
+Pebble is a lightweight, API-driven process supervisor that is responsible for
+configuring processes to run in a container and controlling those processes
+throughout the workload lifecycle.
+
+Pebble `services` are configured through [layers](https://github.com/canonical/pebble#layer-specification),
+and the following containers represent each one a layer forming the effective
+Pebble configuration, or `plan`:
+
+1. An [NGINX](https://www.nginx.com/) container, which can be used to
+efficiently serve static resources, as well as be the incoming point for all web
+traffic to the pod.
+2. The [Synapse](https://github.com/matrix-org/synapse) container itself, which
+has Synapse installed and configured.
+
+As a result, if you run a `kubectl get pods` on a namespace named for the Juju
+model you've deployed the Synapse charm into, you'll see something like the
+following:
+
+```bash
+NAME                             READY   STATUS    RESTARTS   AGE
+synapse-0                         3/3     Running   0         6h4m
+```
+
+This shows there are 3 containers - the two named above, as well as a container
+for the charm code itself.
+
+All containers will have the command `/charm/bin/pebble`. Pebble is responsible for service management, as explained above.
+processes startup as explained above.
+
+## OCI images
+
+We use [Rockcraft](https://canonical-rockcraft.readthedocs-hosted.com/en/latest/)
+to build OCI Images for Synapse and NGINX.
+The images are defined in [NGINX ROCK](https://github.com/canonical/synapse-operator/tree/main/nginx_rock/)
+and [Synapse ROCK](https://github.com/canonical/synapse-operator/tree/main/synapse_rock).
+They are published to [Charmhub](https://charmhub.io/), the official repository
+of charms.
+This is done by publishing a resource to Charmhub as described in the
+[Juju SDK How-to guides](https://juju.is/docs/sdk/publishing).
+
+## Containers
+
+Configuration files for the containers can be found in the respective
+directories that define the ROCKs, see the section above.
+
+### NGINX
+
+This container is the entry point for all web traffic to the pod (on port
+`8080`). Serves static files directly and forwards non-static requests to
+the Synapse container (on port `8008`).
+
+NGINX provides static content cache, reverse proxy, and load balancer among 
+multiple application servers, as well as other features. It can be used in front of
+Synapse server to significantly reduce server and network load.
+
+The workload that this container is running is defined in the [NGINX ROCK](https://github.com/canonical/synapse-operator/tree/main/nginx_rock/).
+
+### Synapse
+
+Synapse is a Python application run by the `start.py` script.
+
+Synapse listens to non-TLS port `8008` serving by default. NGINX can then
+forward non-static traffic to it.
+
+The workload that this container is running is defined in the [Synapse ROCK](https://github.com/canonical/synapse-operator/tree/main/synapse_rock).
+
+## Integrations
+
+See [Integrations](https://charmhub.io/synapse/docs/reference/integrations).
+
+## Charm code overview
+
+The `src/charm.py` is the default entry point for a charm and has the
+`SynapseOperatorCharm` Python class which inherits from the `CharmBase`.
+
+CharmBase is the base class from which all Charms are formed, defined by [Ops](https://juju.is/docs/sdk/ops)
+(Python framework for developing charms).
+
+See more information in [Charm](https://juju.is/docs/sdk/constructs#heading--charm).
+
+The `__init__` method guarantees that the charm observes all events relevant to
+its operation and handles them.
+
+Take, for example, when a configuration is changed by using the CLI.
+
+1. User runs the command
+```bash
+juju config synapse server_name=myserver.myserver.com
+```
+2. A `config-changed` event is emitted
+3. Event handlers are defined in the charm's framework observers. An example looks like the following:
+```python
+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.

docs/how-to/contribute.md

@@ -0,0 +1,119 @@
+# How to contribute
+
+## Overview
+
+This document explains the processes and practices recommended for contributing
+enhancements to the Synapse operator.
+
+- Generally, before developing enhancements to this charm, you should consider
+[opening an issue](https://github.com/canonical/synapse-operator/issues)
+explaining your use case.
+- If you would like to chat with us about your use-cases or proposed
+implementation, you can reach us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev)
+or [Discourse](https://discourse.charmhub.io/).
+- Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk)
+library will help you a lot when working on new features or bug fixes.
+- All enhancements require review before being merged. Code review typically
+examines
+  - code quality
+  - test coverage
+  - user experience for Juju operators of this charm.
+- Please help us out in ensuring easy to review branches by rebasing your pull
+request branch onto the `main` branch. This also avoids merge commits and
+creates a linear Git commit history.
+- Please generate src documentation for every commit. See the section below for
+more details.
+
+## Developing
+
+The code for this charm can be downloaded as follows:
+
+```
+git clone https://github.com/canonical/synapse-operator
+```
+
+You can use the environments created by `tox` for development:
+
+```shell
+tox --notest -e unit
+source .tox/unit/bin/activate
+```
+
+### Testing
+
+Note that the [Synapse](synapse_rock/rockcraft.yaml) and [Synapse NGINX](synapse_nginx_rock/rockcraft.yaml)
+images need to be built and pushed to microk8s for the tests to run. They should
+be tagged as `localhost:32000/synapse:latest` and
+`localhost:32000/synapse-nginx:latest` so that Kubernetes knows how to pull them
+from the MicroK8s repository. Note that the MicroK8s registry needs to be
+enabled using `microk8s enable registry`. More details regarding the OCI images
+below. The following commands can then be used to run the tests:
+
+* `tox`: Runs all of the basic checks (`lint`, `unit`, `static`, and `coverage-report`).
+* `tox -e fmt`: Runs formatting using `black` and `isort`.
+* `tox -e lint`: Runs a range of static code analysis to check the code.
+* `tox -e static`: Runs other checks such as `bandit` for security issues.
+* `tox -e unit`: Runs the unit tests.
+* `tox -e integration`: Runs the integration tests.
+
+### Generating src docs for every commit
+
+Run the following command:
+
+```bash
+echo -e "tox -e src-docs\ngit add src-docs\n" >> .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+## Build charm
+
+Build the charm in this git repository using:
+
+```shell
+charmcraft pack
+```
+For the integration tests (and also to deploy the charm locally), the synapse
+and synapse-nginx images are required in the microk8s registry. To enable it:
+
+    microk8s enable registry
+
+The following commands import the images in the Docker daemon and push them into
+the registry:
+
+    cd [project_dir]/synapse_rock && rockcraft pack rockcraft.yaml
+    skopeo --insecure-policy copy oci-archive:synapse_1.0_amd64.rock docker-daemon:localhost:32000/synapse:latest
+    docker push localhost:32000/synapse:latest
+    cd [project_dir]/nginx_rock && rockcraft pack rockcraft.yaml
+    skopeo --insecure-policy copy oci-archive:synapse_nginx_1.0_amd64.rock docker-daemon:localhost:32000/synapse-nginx:latest
+    docker push localhost:32000/synapse-nginx:latest
+
+### Deploy
+
+```bash
+# Create a model
+juju add-model synapse-dev
+# Enable DEBUG logging
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+# Deploy the charm (assuming you're on amd64)
+juju deploy ./synapse_ubuntu-20.04-amd64.charm \
+  --resource synapse-image=localhost:32000/synapse:latest \
+  --resource synapse-nginx-image=localhost:32000/synapse-nginx:latest
+```
+
+### Configure server_name
+
+Synapse requires a server_name to be set before starting. Note that this cannot
+be changed later so if you want a different server name, will need to run the
+action `reset-instance` to re-create everything.
+
+The following command will configure the server_name mychat.test.com:
+
+```bash
+juju configure synapse server_name=mychat.test.com
+```
+
+Read more about server_name in [Configuring Synapse](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#server_name).
+
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to the Synapse Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.

docs/index.md

@@ -15,11 +15,22 @@ Synapse is an open-source project that welcomes community contributions, suggest
 * [Join the Discourse forum](https://discourse.charmhub.io/tag/synapse)
 * [Discuss on the Mattermost chat service](https://chat.charmhub.io/charmhub/channels/charm-dev)
 * Contribute and report bugs to [the Synapse operator](https://github.com/canonical/synapse-operator)
+* Check the [release notes](https://github.com/canonical/synapse-operator/releases)
 
 ## Contributing to this documentation
 
 Documentation is an important part of this project, and we take the same open-source approach to the documentation as the code. As such, we welcome community contributions, suggestions and constructive feedback on our documentation. Our documentation is hosted on the [Charmhub forum](https://discourse.charmhub.io/) to enable easy collaboration. Please use the “Help us improve this documentation” links on each documentation page to either directly change something you see that’s wrong, or ask a question, or make a suggestion about a potential change via the comments section.
 
 If there’s a particular area of documentation that you’d like to see that’s missing, please [file a bug](https://github.com/canonical/synapse-operator/issues).
 
-# Contents
+# Contents
+
+1. [Tutorial](tutorial)
+  1. [Getting Started](tutorial/getting-started.md)
+1. [How to](how-to)
+  1. [Contribute](how-to/contribute.md)
+1. [Reference](reference)
+  1. [Actions](reference/actions.md)
+  1. [Integrations](reference/integrations.md)
+1. [Explanation](explanation)
+  1. [Charm architecture](explanation/charm-architecture.md)

docs/reference/actions.md

@@ -0,0 +1,3 @@
+# Actions
+
+See [Actions](https://charmhub.io/synapse/actions).

docs/reference/integrations.md

@@ -0,0 +1,76 @@
+# Integrations
+
+### db
+
+_Interface_: pgsql
+_Supported charms_: [postgresql-k8s](https://charmhub.io/postgresql-k8s),
+[postgresql](https://charmhub.io/postgresql)
+
+Database integration is a required relation for the Synapse charm to supply
+structured data
+storage for Synapse.
+
+Example db integrate command: `juju integrate synapse postgresql-k8s:db`
+
+### grafana-dashboard
+
+_Interface_: grafana-dashboard
+_Supported charms_: [grafana-k8s](https://charmhub.io/grafana-k8s)
+
+Grafana-dashboard relation enables quick dashboard access already tailored to
+fit the needs of operators to monitor the charm. The template for the Grafana
+dashboard for Synapse charm can
+be found at `/src/grafana_dashboards/synapse.json`. It was extracted from
+[matrix/synapse repository](https://github.com/matrix-org/synapse/blob/master/contrib/grafana/synapse.json). In Grafana UI, it can be
+found as “Synapse Operator” under the General section of the dashboard browser
+(`/dashboards`). Modifications to the dashboard can be made but will not be
+persisted upon restart/redeployment of the charm.
+
+Grafana-Prometheus integrate command:
+```
+juju integrate grafana-k8s:grafana-source prometheus-k8s:grafana-source
+```
+Grafana-dashboard integrate command:
+```
+juju integrate synapse grafana-dashboard`
+```
+
+### ingress
+
+_Interface_: ingress
+_Supported charms_: [nginx-ingress-integrator](https://charmhub.io/nginx-ingress-integrator),
+[traefik](https://charmhub.io/traefik-k8s)
+
+Ingress manages external http/https access to services in a kubernetes cluster.
+Note that the kubernetes cluster must already have an nginx ingress controller
+already deployed. Documentation to enable ingress in MicroK8s can be found in
+[Addon: Ingress](https://microk8s.io/docs/addon-ingress).
+
+Example ingress integrate command: `juju integrate synapse nginx-ingress-integrator`
+
+### metrics-endpoint
+
+_Interface_: [prometheus_scrape](https://charmhub.io/interfaces/prometheus_scrape-v0)
+_Supported charms_: [prometheus-k8s](https://charmhub.io/prometheus-k8s)
+
+Metrics-endpoint relation allows scraping the `/metrics` endpoint provided by
+Synapse. The metrics are exposed in the [open metrics format](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#data-model) and will only be scraped by Prometheus once the
+relation becomes active. For more information about the metrics exposed, refer to ["How to monitor Synapse metrics using Prometheus"](https://github.com/matrix-org/synapse/blob/master/docs/metrics-howto.md).
+
+Metrics-endpoint integrate command: `juju integrate synapse prometheus-k8s`
+
+### saml
+
+_Interface_: saml
+_Supported charms_: [saml-integrator](https://charmhub.io/saml-integrator/)
+
+Integrating Synapse with SAML Integrator provides SAML configuration details so
+users can be authenticated in via a SAML server.
+
+Example saml integrate command: `juju integrate synapse saml-integrator:saml`
+
+Note that `public_baseurl` configuration set the public-facing base URL that
+clients use to access this Homeserver. It's used as `entity_id` if set instead of
+https://server_name.
+
+See more information in [Charm Architecture](https://charmhub.io/synapse/docs/explanation-charm-architecture).