Various improvements to the docs (#113)

* Various improvements to the docs

-- Improve the docs index

-- Fix s3-configuration tutorial

-- Add integrations reference

-- Minor fixes

README.md

@@ -35,6 +35,7 @@ fixes and constructive feedback.
 * [Join our online chat](https://chat.charmhub.io/charmhub/channels/charm-dev)
 * [Contribute](https://charmhub.io/discourse-k8s/docs/contributing)
 * [Get started](https://charmhub.io/discourse-k8s/docs/getting-started)
+
 Thinking about using the Discourse Operator for your next project? [Get in touch](https://chat.charmhub.io/charmhub/channels/charm-dev)!
 
 ---

docs/Explanation/explanation-charm-architecture.md → docs/explanation/charm-architecture.md

@@ -1,4 +1,4 @@
-# Charm Architecture
+# Charm architecture
 
 At its core, [Discourse](https://www.discourse.org/) is a [Ruby on Rails](https://rubyonrails.org/) application that integrates with [PostgreSQL](https://www.postgresql.org/) and [Redis](https://redis.io/).
 
@@ -33,9 +33,9 @@ The server is started in HTTP mode (port `3000`) serving all the content. Alongs
 
 The workload that this container is running is defined in the [Discourse dockerfile in the charm repository](https://github.com/canonical/discourse-k8s-operator/blob/main/discourse.Dockerfile).
 
-## Docker Images
+## OCI images
 
-The image defined in the [Discourse dockerfile](https://github.com/canonical/discourse-k8s-operator/blob/main/discourse.Dockerfile) in the charm repository is published to [Charmhub](https://charmhub.io/), the official repository of charms.
+The OCI image is built using [Rockcraft](https://canonical-rockcraft.readthedocs-hosted.com) and defined in the [Rockfile](https://github.com/canonical/discourse-k8s-operator/blob/main/discourse_rock/rockcraft.yaml) in the charm repository. It is then published to [Charmhub](https://charmhub.io/), the official repository for 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).
 
@@ -64,25 +64,25 @@ Loki is an open-source fully-featured logging system. This charms is shipped wit
 ### Prometheus
 Prometheus is an open-source systems monitoring and alerting toolkit with a dimensional data model, flexible query language, efficient time series database and modern alerting approach. This charm is shipped with a Prometheus exporter, alerts and support for integrating with the [Prometheus Operator](https://charmhub.io/prometheus-k8s) to automatically scrape the targets.
 
-## Juju Events
+## Juju events
 
 Accordingly to the [Juju SDK](https://juju.is/docs/sdk/event): "an event is a data structure that encapsulates part of the execution context of a charm".
 
 For this charm, the following events are observed:
 
 1. [<container name>_pebble_ready](https://juju.is/docs/sdk/container-name-pebble-ready-event): fired on Kubernetes charms when the requested container is ready. Action: wait for the integrations, and configure the containers.
 2. [config_changed](https://juju.is/docs/sdk/config-changed-event): usually fired in response to a configuration change using the GUI or CLI. Action: wait for the integrations, validate the configuration, update Ingress, and restart the containers.
-4. [add_admin_user_action](https://charmhub.io/discourse-k8s/actions): fired when add-admin-user action is executed. Action: add an admin user with the provided email and password.
-5. [database_relation_joined](https://github.com/canonical/ops-lib-pgsql): PostgreSQLClient custom event for when the connection details to the master database on this relation joins. Action: initialize the database and enable the appropriate extensions.
+3. [add_admin_user_action](https://charmhub.io/discourse-k8s/actions): fired when add-admin-user action is executed. Action: add an admin user with the provided email and password.
+4. [database_relation_joined](https://github.com/canonical/ops-lib-pgsql): PostgreSQLClient custom event for when the connection details to the master database on this relation joins. Action: initialize the database and enable the appropriate extensions.
 5. [master_changed](https://github.com/canonical/ops-lib-pgsql): PostgreSQLClient custom event for when the connection details to the master database on this relation change. Action: update the database connection string configuration and emit config_changed event.
-5. [redis_relation_updated](https://github.com/canonical/redis-k8s-operator): Redis Operator custom event for when the relation details have been updated. Action: wait for the integrations and restart the containers.
+6. [redis_relation_updated](https://github.com/canonical/redis-k8s-operator): Redis Operator custom event for when the relation details have been updated. Action: wait for the integrations and restart the containers.
 
-## Charm Code Overview
+## Charm code overview
 
 The `src/charm.py` is the default entry point for a charm and has the DiscourseCharm Python class which inherits from 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.
+The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them.

docs/Tutorial/container-configuration.md → docs/how-to/configure-container.md

@@ -1,9 +1,9 @@
-# Container configuration
+# How to configure the container
 
 This charm exposes several configurations to tweak the behaviour of discourse. These can by changes by running `juju config [charm_name] [configuration]=[value]`. Below you can find some of the options that will allow you to modify the charm's behaviour:
 
 * CORS policies can be modified with the settings [cors_origin](https://charmhub.io/discourse-k8s/configure#cors_origin) and [enable_cors](https://charmhub.io/discourse-k8s/configure#enable_cors)
 * The developer mails can be set through [developer_emails](https://charmhub.io/discourse-k8s/configure#developer_emails)
 * Throttle level protections provided by discourse can be changed via [throttle_level](https://charmhub.io/discourse-k8s/configure#throttle_level)
 
-For a comprehensive list of configuration options check the [configuration reference](https://charmhub.io/discourse-k8s/configure).
+For a comprehensive list of configuration options check the [configuration reference](https://charmhub.io/discourse-k8s/configure).

docs/how-to/configure-hostname.md

@@ -0,0 +1,49 @@
+# How to configure the hostname
+
+### Prerequisites
+
+Deploy and relate [nginx-ingress-integrator](https://charmhub.io/nginx-ingress-integrator) charm.
+
+```
+juju deploy nginx-ingress-integrator
+juju trust nginx-ingress-integrator --scope cluster # if RBAC is enabled
+juju relate discourse-k8s nginx-ingress-integrator
+```
+
+### Configure hostname
+
+This charm exposes the `external_hostname` configuration option to specify the external hostname of the application.
+
+To configure a different hostname for Discourse, you can configure the ingress hostname through the
+discourse-k8s configuration.
+
+```
+juju config discourse-k8s external_hostname=<desired-hostname>
+```
+
+The output of `juju status` should look similar to the following:
+
+```
+Model           Controller  Cloud/Region        Version  SLA          Timestamp
+tutorial        mk8s        microk8s/localhost  2.9.44   unsupported  18:19:34-04:00
+
+App                       Version  Status  Scale  Charm                     Channel        Rev  Address         Exposed  Message
+discourse-k8s             2.8.14   active      1  discourse-k8s                             41  <discourse-ip>  no
+nginx-ingress-integrator  25.3.0   active      1  nginx-ingress-integrator  latest/stable   81  <ingress-ip>    no       Ingress IP(s): 127.0.0.1, Service IP(s): <ingress-svc-ip>
+postgresql-k8s            14.9     active      1  postgresql-k8s            14/edge        145  <postgres-ip>   no       Primary
+redis-k8s                 7.0.4    active      1  redis-k8s                 latest/edge     26  <redis-ip>      no
+
+Unit                         Workload  Agent  Address           Ports   Message
+discourse-k8s/0*             active    idle   <discourse-ip>
+nginx-ingress-integrator/0*  active    idle   <ingress-ip>              Ingress IP(s): 127.0.0.1, Service IP(s): <ingress-svc-ip>
+postgresql-k8s/0*            active    idle   <postgres-ip>             Primary
+redis-k8s/0*                 active    idle   <redis-ip>    
+```
+
+Note the Service IP(s): next to nginx-ingress-integrator charm’s Status output.
+
+Test the ingress by sending a GET request to the service with `Host` headers.
+
+```
+curl -H "Host: <desired-hostname>" http://<ingress-svc-ip>
+```

docs/Tutorial/s3-configuration.md → docs/how-to/configure-s3.md

@@ -1,4 +1,4 @@
-# S3 configuration
+# How to configure S3
 
 An S3 bucket can be leveraged to serve the static resources packaged by Discourse, potentically improving performance. Moreover, it is required when scaling the charm to serve the uploaded files. To configure it to set the following configuration options with the appropriate values for your existing bucket `juju config [charm_name] [configuration]=[value]`:
 
@@ -16,4 +16,4 @@ To enable S3 to perform backups, you'll need to specify also `s3_backup_bucket`.
 It is also possible to configure the S3 bucket to act as a content delivery network (CDN) serving the static content directly from the bucket, for that, set `s3_cdn_url`. If you wish to modify the CORS set up, you can do so by changing `s3_install_cors_rule`.
 
 
-For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure).
+For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure).

docs/Tutorial/saml-configuration.md → docs/how-to/configure-saml.md

@@ -1,8 +1,8 @@
-# SAML configuration
+# How to configure SAML
 
 To configure Discourse's SAML integration you'll have to set the following configuration options with the appropriate values for your SAML server by running `juju config [charm_name] [configuration]=[value]`.
 
 The SAML URL needs to be scpecified in `saml_target_url`. If you wish to force the login to go through SAML, enable `force_saml_login`.
 The groups to be synced from the provider can be defined in `saml_sync_groups` as a comma-separated list of values.
 
-For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure).
+For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure).

docs/Tutorial/smtp-configuration.md → docs/how-to/configure-smtp.md

@@ -1,4 +1,4 @@
-# SMTP configuration
+# How to configure SMTP
 
 To configure Discourse's SMTP you'll have to set the following configuration options with the appropriate values for your SMTP server by running `juju config [charm_name] [configuration]=[value]`.
 
@@ -8,4 +8,4 @@ If authentication is needed, `smtp_authentication` will need to be set to the ap
 
 If needed, the verification of the SSL certs can be turned on and off with `smtp_openssl_verify_mode`.
 
-For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure).
+For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure).

docs/how-to/contribute.md

@@ -0,0 +1,104 @@
+# How to contribute
+
+## Overview
+
+This document explains the processes and practices recommended for contributing
+enhancements to the Discourse operator.
+
+- Generally, before developing enhancements to this charm, you should consider
+[opening an issue](https://github.com/canonical/discourse-k8s-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/discourse-k8s-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 [Discourse](discourse_rock/rockcraft.yaml) image need to be built and 
+pushed to microk8s for the tests to run. It should
+be tagged as `localhost:32000/discourse: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 image
+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 discourse 
+image is required in the microk8s registry. To enable it:
+
+```shell
+    microk8s enable registry
+```
+
+The following commands import the images in the Docker daemon and push them into
+the registry:
+
+```shell
+    cd [project_dir]/discourse_rock && rockcraft pack rockcraft.yaml
+    skopeo --insecure-policy copy oci-archive:discourse_1.0_amd64.rock docker-daemon:localhost:32000/discourse:latest
+    docker push localhost:32000/discourse:latest
+```
+
+### Deploy
+
+```bash
+# Create a model
+juju add-model discourse-dev
+# Enable DEBUG logging
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+# Deploy the charm (assuming you're on amd64)
+juju deploy ./discourse-k8s_ubuntu-20.04-amd64.charm \
+  --resource discourse-image=localhost:32000/discourse:latest \
+```
+
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to the Discourse Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.

docs/Tutorial/upgrades.md → docs/how-to/upgrade.md

@@ -1,8 +1,9 @@
-# Upgrades
+# How to upgrade
 
 Upgrades are done just by running the `juju refresh` subcommand. Juju, Kubernetes, and Discourse then work together to ensure that one pod is upgraded to the new version and makes any database schema changes before the rest of the pods are upgraded in their turn.
 
 ## Upgrading from pod-spec to sidecar
+
 It is recommended to take a database backup before starting an upgrade from pod-spec to the sidecar version of the discourse-k8s charm.
 
 When upgrading from the pod-spec charm some downtime is to be expected. The existing Deployment will be deleted and a new StatefulSet will be created from scratch. Hence, the charm will be unresponsive while the discourse image resource is downloaded from the Charmhub registry and the first unit is spun up.
@@ -41,4 +42,4 @@ Given that the image is now packed and released as a charm resource, the followi
 * `image_user`
 * `image_pass`
 
-You can use a different image than the one deployed by default with the charm using the [attach-resource](https://juju.is/docs/olm/juju-attach-resource) juju command.
+You can use a different image than the one deployed by default with the charm using the [attach-resource](https://juju.is/docs/olm/juju-attach-resource) juju command.