From 739823550d35c82d947ad4a9eb0ae650d84a7f06 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Mon, 23 Sep 2024 13:56:16 +0000
Subject: [PATCH 1/5] modified: docs/index.md // removed:
 docs/how-to/backup-and-restore.md,docs/reference/external-access.md

---
 docs/how-to/backup-and-restore.md | 57 -------------------------------
 docs/index.md                     |  4 +--
 docs/reference/external-access.md | 16 ---------
 3 files changed, 1 insertion(+), 76 deletions(-)
 delete mode 100644 docs/how-to/backup-and-restore.md
 delete mode 100644 docs/reference/external-access.md

diff --git a/docs/how-to/backup-and-restore.md b/docs/how-to/backup-and-restore.md
deleted file mode 100644
index 63c60973..00000000
--- a/docs/how-to/backup-and-restore.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# How to back up and restore Discourse
-
-This document shows how to back up and restore Discourse.
-
-There are two ways to backup and restore Discourse. The
-first one is using the backup functionality provided by Discourse.
-
-The second one consists in backing up and restoring the database directly,
-that can be done easily thanks to [Charmed PostgreSQL](https://charmhub.io/postgresql)
-and [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s).
-
-For this How-to, it is supposed that S3 has been configured (see [how to configure S3](./configure-s3.md).
-Running the Discourse Operator without S3 configured is not recommended as it will not work in HA mode and
-it is risky and data loss can happen if the workload container is restarted.
-
-
-## Backup and restore using Discourse backup functionality
-
-It is recommended to configure the `s3_backup_bucket` to a bucket that will store the
-backups (see [how to configure S3](./configure-s3.md)). If  `s3_backup_bucket` is not set,
-the backups will be placed in one of the workload containers,
-in the path `/srv/discourse/app/public/backups/`. This will make HA deployments work incorrectly.
-Besides, it will be necessary to get the backup files and put them in a more secure place,
-using Discourse admin interface or [juju scp](https://juju.is/docs/juju/juju-scp).
-
-A backup can be made by a site administrator using the web interface. See
-[Create, download, and restore a backup of your Discourse database](https://meta.discourse.org/t/create-download-and-restore-a-backup-of-your-discourse-database/122710/1)
-for the full process.
-
-Backups can also be configured to be automatically created. See [Configure automatic backups for Discourse](https://meta.discourse.org/t/configure-automatic-backups-for-discourse/14855/1) for the full process.
-
-
-## Backup and restore using PostgreSQL
-
-If the same S3 bucket can be used in the restored Discourse instance, then it is only necessary
-to backup the database.
-
-This can be easily done with [Charmed PostgreSQL](https://charmhub.io/postgresql) and [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s).
-See [How to create and list backups in Charmed PostgreSQL](https://charmhub.io/postgresql/docs/h-create-and-list-backups)
-or [How to create and list backups in Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s/docs/h-create-and-list-backups) for the full procedure.
-
-To restore Discourse, once it is deployed and configured as the Discourse instance to restore, it is only necessary
-to restore the database. The instructions, depending on the configuration, can be found in the next links:
- - Charmed PostgreSQL. Local backup: https://charmhub.io/postgresql/docs/h-restore-backup
- - Charmed PostgreSQL. Migrate a cluster: https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore
- - Charmed PostgreSQL K8s. Local backup: https://charmhub.io/postgresql-k8s/docs/h-restore-backup
- - Charmed PostgreSQL K8s. Migrate a cluster: https://charmhub.io/postgresql-k8s/docs/h-migrate-cluster-via-restore
-
-## S3 and the backup and restore procedure
-
-If S3 is configured, the S3 bucket contains all the uploaded files. This information should also be backed up,
-but it is not explained in this How-to.
-
-If the S3 bucket used in the restored Discourse is not the same bucket as the original one, extra steps must be
-done, see [moving from one S3 bucket to another](https://meta.discourse.org/t/moving-from-one-s3-bucket-to-another/184779)
-for more information. You can run the remap command with: `juju ssh --container discourse discourse-k8s/0 pebble  exec --context=discourse --user=_daemon_ -w=/srv/discourse/app/ -- bundle exec /srv/discourse/app/script/discourse backup`
-and rake tasks with a command like: `juju ssh --container discourse discourse-k8s/0 pebble exec --context=discourse --user=_daemon_ -w=/srv/discourse/app/ -- bundle exec rake posts:rebake`.
diff --git a/docs/index.md b/docs/index.md
index a2a35191..a56e0e82 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -44,11 +44,9 @@ fixes and constructive feedback.
   1. [How to configure SMTP](how-to/configure-smtp.md)
   1. [How to contribute](how-to/contribute.md)
   1. [How to upgrade](how-to/upgrade.md)
-  1. [How to backup and restore](how-to/backup-and-restore.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)
   1. [Configurations](reference/configurations.md)
   1. [Integrations](reference/integrations.md)
   1. [Plugins](reference/plugins.md)
-  1. [External Access](reference/external-access.md)
-1. [Getting started](tutorial.md)
+1. [Getting started](tutorial.md)
\ No newline at end of file
diff --git a/docs/reference/external-access.md b/docs/reference/external-access.md
deleted file mode 100644
index cec7d8ed..00000000
--- a/docs/reference/external-access.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# External access required by the Charm
-
-Depending on the configuration of the charm, the following external accesses are needed:
- - Access to the PostgreSQL database (mandatory).
- - Access to the S3 server is S3 is configured in the charm.
- - Access to http://github.com to download Promtail if the logging interface is used in the charm.
-
-If the option "external system avatars enabled" is enabled in the admin, access
-to https://avatars.discourse.org is necessary.
-
-Besides that, other services, like link previews and installing themes from a git repository
-may need access to external sites to work, so allowing internet access to the Discourse instance is
-recommended. In restricted environments, the `model-config` options `juju-http-proxy`, `juju-https-proxy`
-and `juju-no-proxy` can be used to set up a proxy for Discourse,
-see [Using proxies with Charmed Kubernetes](https://ubuntu.com/kubernetes/docs/proxies) for
-more information.
\ No newline at end of file

From 335b334da36f26d39c7e952a1e93e3caf0f85b69 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 26 Sep 2024 07:48:44 +0000
Subject: [PATCH 2/5] modified:
 docs/reference/actions.md,docs/reference/configurations.md

---
 docs/reference/actions.md        | 4 +++-
 docs/reference/configurations.md | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/reference/actions.md b/docs/reference/actions.md
index 2dd1a081..d6dd2bb6 100644
--- a/docs/reference/actions.md
+++ b/docs/reference/actions.md
@@ -1,3 +1,5 @@
 # Actions
 
-See [Actions](https://charmhub.io/discourse-k8s/actions).
\ No newline at end of file
+See [Actions](https://charmhub.io/discourse-k8s/actions).
+
+> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)
\ No newline at end of file
diff --git a/docs/reference/configurations.md b/docs/reference/configurations.md
index f47cbe3e..e25aa557 100644
--- a/docs/reference/configurations.md
+++ b/docs/reference/configurations.md
@@ -1,3 +1,5 @@
 # Configurations
 
-See [Configure](https://charmhub.io/discourse-k8s/configure).
\ No newline at end of file
+See [Configurations](https://charmhub.io/discourse-k8s/configure).
+
+> Read more about configurations in the Juju docs: [Configuration](https://juju.is/docs/juju/configuration)
\ No newline at end of file

From 10fad3c9a427a50d737a7afdc46d476e67a0c120 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 26 Sep 2024 07:49:11 +0000
Subject: [PATCH 3/5] modified:
 docs/how-to/configure-s3.md,docs/how-to/access--the-rails-console.md,docs/how-to/contribute.md,docs/reference/integrations.md,docs/how-to/configure-container.md,docs/index.md,docs/tutorial.md,docs/how-to/configure-saml.md
 // new: docs/how-to/backup-and-restore.md

---
 docs/how-to/access--the-rails-console.md |  2 +-
 docs/how-to/backup-and-restore.md        | 57 ++++++++++++++++++++++++
 docs/how-to/configure-container.md       |  2 +-
 docs/how-to/configure-s3.md              |  2 +-
 docs/how-to/configure-saml.md            |  2 +-
 docs/how-to/contribute.md                |  2 +-
 docs/index.md                            | 18 ++++----
 docs/reference/integrations.md           | 25 +++++++++--
 docs/tutorial.md                         |  2 +-
 9 files changed, 94 insertions(+), 18 deletions(-)
 create mode 100644 docs/how-to/backup-and-restore.md

diff --git a/docs/how-to/access--the-rails-console.md b/docs/how-to/access--the-rails-console.md
index 3d14a919..a3900990 100644
--- a/docs/how-to/access--the-rails-console.md
+++ b/docs/how-to/access--the-rails-console.md
@@ -26,4 +26,4 @@ If the output of the last command contains something similar to this:
 Loading production environment (Rails 7.0.5.1)
 irb(main):001:0>
 ```
-Congratulations, you have accessed the rails console.
+Congratulations, you have accessed the rails console.
\ No newline at end of file
diff --git a/docs/how-to/backup-and-restore.md b/docs/how-to/backup-and-restore.md
new file mode 100644
index 00000000..e710d1fb
--- /dev/null
+++ b/docs/how-to/backup-and-restore.md
@@ -0,0 +1,57 @@
+# How to back up and restore Discourse
+
+This document shows how to back up and restore Discourse.
+
+There are two ways to backup and restore Discourse. The
+first one is using the backup functionality provided by Discourse.
+
+The second one consists in backing up and restoring the database directly,
+that can be done easily thanks to [Charmed PostgreSQL](https://charmhub.io/postgresql)
+and [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s).
+
+For this How-to, it is supposed that S3 has been configured (see [how to configure S3](./configure-s3.md).
+Running the Discourse Operator without S3 configured is not recommended as it will not work in HA mode and
+it is risky and data loss can happen if the workload container is restarted.
+
+
+## Backup and restore using Discourse backup functionality
+
+It is recommended to configure the `s3_backup_bucket` to a bucket that will store the
+backups (see [how to configure S3](./configure-s3.md)). If  `s3_backup_bucket` is not set,
+the backups will be placed in one of the workload containers,
+in the path `/srv/discourse/app/public/backups/`. This will make HA deployments work incorrectly.
+Besides, it will be necessary to get the backup files and put them in a more secure place,
+using Discourse admin interface or [juju scp](https://juju.is/docs/juju/juju-scp).
+
+A backup can be made by a site administrator using the web interface. See
+[Create, download, and restore a backup of your Discourse database](https://meta.discourse.org/t/create-download-and-restore-a-backup-of-your-discourse-database/122710/1)
+for the full process.
+
+Backups can also be configured to be automatically created. See [Configure automatic backups for Discourse](https://meta.discourse.org/t/configure-automatic-backups-for-discourse/14855/1) for the full process.
+
+
+## Backup and restore using PostgreSQL
+
+If the same S3 bucket can be used in the restored Discourse instance, then it is only necessary
+to backup the database.
+
+This can be easily done with [Charmed PostgreSQL](https://charmhub.io/postgresql) and [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s).
+See [How to create and list backups in Charmed PostgreSQL](https://charmhub.io/postgresql/docs/h-create-and-list-backups)
+or [How to create and list backups in Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s/docs/h-create-and-list-backups) for the full procedure.
+
+To restore Discourse, once it is deployed and configured as the Discourse instance to restore, it is only necessary
+to restore the database. The instructions, depending on the configuration, can be found in the next links:
+ - Charmed PostgreSQL. Local backup: https://charmhub.io/postgresql/docs/h-restore-backup
+ - Charmed PostgreSQL. Migrate a cluster: https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore
+ - Charmed PostgreSQL K8s. Local backup: https://charmhub.io/postgresql-k8s/docs/h-restore-backup
+ - Charmed PostgreSQL K8s. Migrate a cluster: https://charmhub.io/postgresql-k8s/docs/h-migrate-cluster-via-restore
+
+## S3 and the backup and restore procedure
+
+If S3 is configured, the S3 bucket contains all the uploaded files. This information should also be backed up,
+but it is not explained in this How-to.
+
+If the S3 bucket used in the restored Discourse is not the same bucket as the original one, extra steps must be
+done, see [moving from one S3 bucket to another](https://meta.discourse.org/t/moving-from-one-s3-bucket-to-another/184779)
+for more information. You can run the remap command with: `juju ssh --container discourse discourse-k8s/0 pebble  exec --context=discourse --user=_daemon_ -w=/srv/discourse/app/ -- bundle exec /srv/discourse/app/script/discourse backup`
+and rake tasks with a command like: `juju ssh --container discourse discourse-k8s/0 pebble exec --context=discourse --user=_daemon_ -w=/srv/discourse/app/ -- bundle exec rake posts:rebake`.
\ No newline at end of file
diff --git a/docs/how-to/configure-container.md b/docs/how-to/configure-container.md
index a9df0587..f01012a7 100644
--- a/docs/how-to/configure-container.md
+++ b/docs/how-to/configure-container.md
@@ -6,4 +6,4 @@ This charm exposes several configurations to tweak the behaviour of Discourse. T
 * 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).
\ No newline at end of file
diff --git a/docs/how-to/configure-s3.md b/docs/how-to/configure-s3.md
index 17c7d78e..99b1f5f3 100644
--- a/docs/how-to/configure-s3.md
+++ b/docs/how-to/configure-s3.md
@@ -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).
\ No newline at end of file
diff --git a/docs/how-to/configure-saml.md b/docs/how-to/configure-saml.md
index 4158f354..29f6f8f2 100644
--- a/docs/how-to/configure-saml.md
+++ b/docs/how-to/configure-saml.md
@@ -13,4 +13,4 @@ juju config saml-integrator entity_id=https://login.staging.ubuntu.com
 juju integrate discourse-k8s saml-integrator
 ```
 
-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).
\ No newline at end of file
diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md
index 500e20d2..41bea7af 100644
--- a/docs/how-to/contribute.md
+++ b/docs/how-to/contribute.md
@@ -100,4 +100,4 @@ juju deploy ./discourse-k8s_ubuntu-20.04-amd64.charm \
 
 ## 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.
+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.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index a56e0e82..3093119b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -36,17 +36,19 @@ fixes and constructive feedback.
 1. [Explanation](explanation)
   1. [Charm architecture](explanation/charm-architecture.md)
 1. [How To](how-to)
-  1. [How to access the Rails console](how-to/access--the-rails-console.md)
-  1. [How to configure the container](how-to/configure-container.md)
-  1. [How to configure the hostname](how-to/configure-hostname.md)
-  1. [How to configure S3](how-to/configure-s3.md)
-  1. [How to configure SAML](how-to/configure-saml.md)
-  1. [How to configure SMTP](how-to/configure-smtp.md)
-  1. [How to contribute](how-to/contribute.md)
-  1. [How to upgrade](how-to/upgrade.md)
+  1. [Access the Rails console](how-to/access--the-rails-console.md)
+  1. [Backup and restore](how-to/backup-and-restore.md)
+  1. [Configure the container](how-to/configure-container.md)
+  1. [Configure the hostname](how-to/configure-hostname.md)
+  1. [Configure S3](how-to/configure-s3.md)
+  1. [Configure SAML](how-to/configure-saml.md)
+  1. [Configure SMTP](how-to/configure-smtp.md)
+  1. [Contribute](how-to/contribute.md)
+  1. [Upgrade](how-to/upgrade.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)
   1. [Configurations](reference/configurations.md)
+  1. [External Access](reference/external-access.md)
   1. [Integrations](reference/integrations.md)
   1. [Plugins](reference/plugins.md)
 1. [Getting started](tutorial.md)
\ No newline at end of file
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
index 9e2d2628..cd9b1f40 100644
--- a/docs/reference/integrations.md
+++ b/docs/reference/integrations.md
@@ -3,17 +3,22 @@
 ### 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 Discourse charm to supply
 structured data storage for Discourse.
 
-Database integrate command: `juju integrate discourse-k8s postgresql-k8s`
+Database integrate command: 
+```
+juju integrate discourse-k8s postgresql-k8s
+```
 
 ### grafana-dashboard
 
 _Interface_: grafana-dashboard
+
 _Supported charms_: [grafana-k8s](https://charmhub.io/grafana-k8s)
 
 Grafana-dashboard relation enables quick dashboard access already tailored to
@@ -35,6 +40,7 @@ juju integrate discourse-k8s grafana-dashboard`
 ### ingress
 
 _Interface_: ingress
+
 _Supported charms_: [nginx-ingress-integrator](https://charmhub.io/nginx-ingress-integrator),
 [traefik](https://charmhub.io/traefik-k8s)
 
@@ -43,24 +49,35 @@ 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).
 
-Ingress integrate command: `juju integrate discourse-k8s nginx-ingress-integrator`
+Ingress integrate command: 
+```
+juju integrate discourse-k8s 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 Discourse.
 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 Discourse metrics using Prometheus"](https://meta.discourse.org/t/discourse-prometheus/72666).
 
-Metrics-endpoint integrate command: `juju integrate discourse-k8s prometheus-k8s`
+Metrics-endpoint integrate command: 
+```
+juju integrate discourse-k8s prometheus-k8s
+```
 
 ### redis
 
 _Interface_: redis  
+
 _Supported charms_: [redis-k8s](https://charmhub.io/redis-k8s)
 
 Discourse uses Redis to run background tasks (with Sidekiq) and keep the application fast and responsive. It enables real-time updates on the pages and helps in managing data efficiently. Redis also helps Discourse in balancing loads by managing rate limits, making it a crucial part of its system.
 
-Redis integrate commands: `juju integrate discourse-k8s redis-k8s`
\ No newline at end of file
+Redis integrate commands: 
+```
+juju integrate discourse-k8s redis-k8s
+```
\ No newline at end of file
diff --git a/docs/tutorial.md b/docs/tutorial.md
index 664d49de..f815e5c4 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -118,4 +118,4 @@ model environment that you've created using the following command:
 
 ```
 juju destroy-model discourse --destroy-storage
-```
+```
\ No newline at end of file

From edd5a1fab23b3a639b9f12e2766e74249d06ab1e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 26 Nov 2024 06:52:09 +0000
Subject: [PATCH 4/5] modified: docs/tutorial.md,docs/index.md

---
 docs/index.md    |  27 +++++--------
 docs/tutorial.md | 101 ++++++++++++++++-------------------------------
 2 files changed, 44 insertions(+), 84 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index b8cd0f1a..3093119b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,17 +1,11 @@
-# Discourse Operator
-A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing Discourse on Kubernetes.
+This charm simplifies initial deployment and "day N" operations of Discourse
+on Kubernetes, such as scaling the number of instances, integration with SSO,
+access to S3 for redundant file storage and more. It allows for deployment on
+many different Kubernetes platforms, from [MicroK8s](https://microk8s.io) or
+[Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes
+offerings.
 
-Discourse is an open-source software application used to create customer-friendly and community-friendly discussion platforms, 
-forums, and mailing lists. It's designed to work as a discussion platform for various topics and is widely used by numerous 
-organizations and individuals to build communities, provide customer support, and facilitate conversations. The platform is 
-built with a focus on simplicity, user-friendliness, and responsiveness, making it accessible from both desktops and mobile 
-devices. Discourse provides various moderation and administration tools, enabling community managers to maintain a healthy and 
-constructive environment.
-
-This charm simplifies operations of Discourse on Kubernetes, such as scaling the number of instances, integration 
-with SSO, access to S3 for redundant file storage and more. It allows for deployment on many different Kubernetes 
-platforms, from [MicroK8s](https://microk8s.io) or [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud 
-Kubernetes offerings.
+Discourse is an open-source software application used to create customer-friendly and community-friendly discussion platforms, forums, and mailing lists. It's designed to work as a discussion platform for various topics and is widely used by numerous organizations and individuals to build communities, provide customer support, and facilitate conversations. The platform is built with a focus on simplicity, user-friendliness, and responsiveness, making it accessible from both desktops and mobile devices. Discourse provides various moderation and administration tools, enabling community managers to maintain a healthy and constructive environment.
 
 ## In this documentation
 
@@ -39,7 +33,8 @@ fixes and constructive feedback.
 
 # Contents
 
-1. [Tutorial](tutorial.md)
+1. [Explanation](explanation)
+  1. [Charm architecture](explanation/charm-architecture.md)
 1. [How To](how-to)
   1. [Access the Rails console](how-to/access--the-rails-console.md)
   1. [Backup and restore](how-to/backup-and-restore.md)
@@ -56,6 +51,4 @@ fixes and constructive feedback.
   1. [External Access](reference/external-access.md)
   1. [Integrations](reference/integrations.md)
   1. [Plugins](reference/plugins.md)
-  1. [External Access](reference/external-access.md)
-1. [Explanation](explanation)
-  1. [Charm architecture](explanation/charm-architecture.md)
+1. [Getting started](tutorial.md)
\ No newline at end of file
diff --git a/docs/tutorial.md b/docs/tutorial.md
index 3acb372f..f815e5c4 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -9,31 +9,18 @@
 In this tutorial, we'll go through each step of the process to get a basic Discourse deployment.
 
 ## Requirements
-- A working station, e.g., a laptop, with amd64 architecture.
-- Juju 3 installed and bootstrapped to a MicroK8s controller. You can accomplish this process by using a Multipass VM as outlined in this guide: [Set up / Tear down your test environment](https://juju.is/docs/juju/set-up--tear-down-your-test-environment)
-- NGINX Ingress Controller. If you're using [MicroK8s](https://microk8s.io/), this can be done by running the command `microk8s enable ingress`. For more details, see [Addon: Ingress](https://microk8s.io/docs/addon-ingress).
 
-For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
+* A laptop or desktop running Ubuntu (or you can use a VM).
+* Juju and [Microk8s](https://juju.is/docs/olm/microk8s) installed. We’ll also want to make sure the ingress add-on is enabled, which we can do by running `microk8s enable ingress`.
 
-:warning: When using a Multipass VM, make sure to replace `127.0.0.1` IP addresses with the
-VM IP in steps that assume you're running locally. To get the IP address of the
-Multipass instance run ```multipass info my-juju-vm```.
 ## Steps
 
-### Shell into the Multipass VM
-> NOTE: If you're working locally, you don't need to do this step.
+### Set up environment
 
-To be able to work inside the Multipass VM first you need to log in with the following command:
-```
-multipass shell my-juju-vm
-```
-
-### Add a Juju model for the tutorial
-
-To easily clean up the resources and separate your workload from the contents of this tutorial, set up a new Juju model named `discourse-tutorial`:
+To easily clean up the resources and separate your workload from the contents of this tutorial, set up a new Juju model named `discourse`:
 
 ```
-juju add-model discourse-tutorial
+juju add-model discourse
 ```
 
 ### Deploy the charms
@@ -51,10 +38,11 @@ juju deploy discourse-k8s
 
 Enable the required PostgreSQL extensions:
 ```
-juju config postgresql-k8s plugin_hstore_enable=True plugin_pg_trgm_enable=True
+juju config postgresql-k8s plugin_hstore_enable=True
+juju config postgresql-k8s plugin_pg_trgm_enable=True
 ```
 
-### Integrate with the Redis k8s charm the PostgreSQL k8s charm
+### Integrate the charms
 
 Integrate `redis-k8s` and `postgresql-k8s` to `discourse-k8s`:
 ```
@@ -64,62 +52,48 @@ juju integrate discourse-k8s postgresql-k8s
 
 By running `juju status --relations` the current state of the deployment can be queried:
 ```
-Model               Controller  Cloud/Region        Version  SLA          Timestamp
-discourse-tutorial  microk8s    microk8s/localhost  3.5.4    unsupported  14:07:18+03:00
+Model      Controller  Cloud/Region        Version  SLA          Timestamp
+discourse  microk8s    microk8s/localhost  3.1.7    unsupported  12:48:02+02:00
 
-App             Version  Status  Scale  Charm           Channel        Rev  Address         Exposed  Message
-discourse-k8s   3.3.0    active      1  discourse-k8s   latest/stable  173  10.152.183.231  no
-postgresql-k8s  14.12    active      1  postgresql-k8s  14/stable      381  10.152.183.143  no
-redis-k8s       7.2.5    active      1  redis-k8s       latest/edge     36  10.152.183.188  no
+App             Version  Status  Scale  Charm           Channel      Rev  Address         Exposed  Message
+discourse-k8s   3.2.0    active      1  discourse-k8s   stable        95  10.152.183.175  no       
+postgresql-k8s  14.10    active      1  postgresql-k8s  14/stable    193  10.152.183.59   no       
+redis-k8s       7.0.4    active      1  redis-k8s       latest/edge   27  10.152.183.46   no       
 
 Unit               Workload  Agent  Address      Ports  Message
-discourse-k8s/0*   active    idle   10.1.32.182
-postgresql-k8s/0*  active    idle   10.1.32.184         Primary
-redis-k8s/0*       active    idle   10.1.32.181
+discourse-k8s/0*   active    idle   10.1.44.214         
+postgresql-k8s/0*  active    idle   10.1.44.219         
+redis-k8s/0*       active    idle   10.1.44.227         
 
 Integration provider           Requirer                       Interface          Type     Message
-discourse-k8s:restart          discourse-k8s:restart          rolling_op         peer
-postgresql-k8s:database        discourse-k8s:database         postgresql_client  regular
-postgresql-k8s:database-peers  postgresql-k8s:database-peers  postgresql_peers   peer
-postgresql-k8s:restart         postgresql-k8s:restart         rolling_op         peer
-postgresql-k8s:upgrade         postgresql-k8s:upgrade         upgrade            peer
-redis-k8s:redis                discourse-k8s:redis            redis              regular
-redis-k8s:redis-peers          redis-k8s:redis-peers          redis-peers        peer
+discourse-k8s:restart          discourse-k8s:restart          rolling_op         peer     
+postgresql-k8s:database        discourse-k8s:database         postgresql_client  regular  
+postgresql-k8s:database-peers  postgresql-k8s:database-peers  postgresql_peers   peer     
+postgresql-k8s:restart         postgresql-k8s:restart         rolling_op         peer     
+postgresql-k8s:upgrade         postgresql-k8s:upgrade         upgrade            peer     
+redis-k8s:redis                discourse-k8s:redis            redis              regular  
+redis-k8s:redis-peers          redis-k8s:redis-peers          redis-peers        peer     
 ```
 The deployment finishes when all the charms show `Active` states.
 
-Run `kubectl get pods -n discourse-tutorial` to see the pods that are being created by the charms:
+Run `kubectl get pods -n discourse` to see the pods that are being created by the charms:
 ```
 NAME                             READY   STATUS    RESTARTS   AGE
-modeloperator-c584f6f9f-qf9gr    1/1     Running   0          5m30s
+modeloperator-64c58d675d-csj47   1/1     Running   0          5m30s
 redis-k8s-0                      3/3     Running   0          5m22s
 discourse-k8s-0                  2/2     Running   0          5m1s
 postgresql-k8s-0                 2/2     Running   0          5m9s
 ```
 
-### Provide ingress capabilities
+### Provide ingress capabilities 
 
 In order to expose the charm, the Nginx Ingress Integrator needs to be deployed and integrated with Discourse:
 
 ```
 juju deploy nginx-ingress-integrator
-```
-To check if RBAC is enabled run the following command:
-```
-microk8s status | grep rbac
-```
-If it is enabled, then the output should be like the following:
-```
-rbac                 # (core) Role-Based Access Control for authorisation
-```
-If the output is empty then RBAC is not enabled.
-
-If your cluster has RBAC enabled, you'll be prompted to run the following command:
-```
+# If your cluster has RBAC enabled you'll be prompted to run the following:
 juju trust nginx-ingress-integrator --scope=cluster
-```
-Then you need to integrate the charm with Nginx Ingress Integrator:
-```
+
 juju integrate discourse-k8s nginx-ingress-integrator
 ```
 
@@ -129,9 +103,7 @@ To create an admin user, use the `create-user` action:
 ```
 juju run discourse-k8s/0 create-user admin=true email=email@example.com
 ```
-The command will return the password of the created user. Discourse will be deployed with `discourse-k8s` as default hostname.
-
-If you are following the tutorial in your local machine, modify your `/etc/hosts` file so that it points to `127.0.0.1`:
+The command will return the password of the created user. Discourse will be deployed with `discourse-k8s` as default hostname. In order to reach it, modify your `/etc/hosts` file so that it points to `127.0.0.1`:
 
 ```
 echo 127.0.0.1 discourse-k8s >> /etc/hosts
@@ -139,16 +111,11 @@ echo 127.0.0.1 discourse-k8s >> /etc/hosts
 
 After that, visit `http://discourse-k8s` to reach Discourse, using the credentials returned from the `create-user` action to login.
 
-### Clean up the environment
+### Clean up the environment 
 
-Congratulations! You have successfully finished the Discourse tutorial. You can now remove the
+Congratulations! You have successfully finished the Discourse tutorial. You can now remove the 
 model environment that you've created using the following command:
 
 ```
-juju destroy-model discourse-tutorial --destroy-storage
-```
-If you used Multipass, to remove the Multipass instance you created for this tutorial, use the following command.
-```
-multipass delete --purge my-juju-vm
-```
-Finally, remove the `127.0.0.1 discourse-k8s` line from the `/etc/hosts` file.
+juju destroy-model discourse --destroy-storage
+```
\ No newline at end of file

From 1122191eb3a6632f2adf1d25897410ac17ce7591 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 16 Jan 2025 07:33:34 +0000
Subject: [PATCH 5/5] modified: docs/index.md,docs/tutorial.md

---
 docs/index.md    |  26 +++++++-----
 docs/tutorial.md | 101 +++++++++++++++++++++++++++++++----------------
 2 files changed, 83 insertions(+), 44 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 3093119b..9239a9c5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,11 +1,17 @@
-This charm simplifies initial deployment and "day N" operations of Discourse
-on Kubernetes, such as scaling the number of instances, integration with SSO,
-access to S3 for redundant file storage and more. It allows for deployment on
-many different Kubernetes platforms, from [MicroK8s](https://microk8s.io) or
-[Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes
-offerings.
+# Discourse Operator
+A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing Discourse on Kubernetes.
 
-Discourse is an open-source software application used to create customer-friendly and community-friendly discussion platforms, forums, and mailing lists. It's designed to work as a discussion platform for various topics and is widely used by numerous organizations and individuals to build communities, provide customer support, and facilitate conversations. The platform is built with a focus on simplicity, user-friendliness, and responsiveness, making it accessible from both desktops and mobile devices. Discourse provides various moderation and administration tools, enabling community managers to maintain a healthy and constructive environment.
+Discourse is an open-source software application used to create customer-friendly and community-friendly discussion platforms, 
+forums, and mailing lists. It's designed to work as a discussion platform for various topics and is widely used by numerous 
+organizations and individuals to build communities, provide customer support, and facilitate conversations. The platform is 
+built with a focus on simplicity, user-friendliness, and responsiveness, making it accessible from both desktops and mobile 
+devices. Discourse provides various moderation and administration tools, enabling community managers to maintain a healthy and 
+constructive environment.
+
+This charm simplifies operations of Discourse on Kubernetes, such as scaling the number of instances, integration 
+with SSO, access to S3 for redundant file storage and more. It allows for deployment on many different Kubernetes 
+platforms, from [MicroK8s](https://microk8s.io) or [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud 
+Kubernetes offerings.
 
 ## In this documentation
 
@@ -33,8 +39,7 @@ fixes and constructive feedback.
 
 # Contents
 
-1. [Explanation](explanation)
-  1. [Charm architecture](explanation/charm-architecture.md)
+1. [Tutorial](tutorial.md)
 1. [How To](how-to)
   1. [Access the Rails console](how-to/access--the-rails-console.md)
   1. [Backup and restore](how-to/backup-and-restore.md)
@@ -51,4 +56,5 @@ fixes and constructive feedback.
   1. [External Access](reference/external-access.md)
   1. [Integrations](reference/integrations.md)
   1. [Plugins](reference/plugins.md)
-1. [Getting started](tutorial.md)
\ No newline at end of file
+1. [Explanation](explanation)
+  1. [Charm architecture](explanation/charm-architecture.md)
\ No newline at end of file
diff --git a/docs/tutorial.md b/docs/tutorial.md
index f815e5c4..c651c30d 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -9,18 +9,31 @@
 In this tutorial, we'll go through each step of the process to get a basic Discourse deployment.
 
 ## Requirements
+- A working station, e.g., a laptop, with amd64 architecture.
+- Juju 3 installed and bootstrapped to a MicroK8s controller. You can accomplish this process by using a Multipass VM as outlined in this guide: [Set up / Tear down your test environment](https://juju.is/docs/juju/set-up--tear-down-your-test-environment)
+- NGINX Ingress Controller. If you're using [MicroK8s](https://microk8s.io/), this can be done by running the command `microk8s enable ingress`. For more details, see [Addon: Ingress](https://microk8s.io/docs/addon-ingress).
 
-* A laptop or desktop running Ubuntu (or you can use a VM).
-* Juju and [Microk8s](https://juju.is/docs/olm/microk8s) installed. We’ll also want to make sure the ingress add-on is enabled, which we can do by running `microk8s enable ingress`.
+For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
 
+:warning: When using a Multipass VM, make sure to replace `127.0.0.1` IP addresses with the
+VM IP in steps that assume you're running locally. To get the IP address of the
+Multipass instance run ```multipass info my-juju-vm```.
 ## Steps
 
-### Set up environment
+### Shell into the Multipass VM
+> NOTE: If you're working locally, you don't need to do this step.
 
-To easily clean up the resources and separate your workload from the contents of this tutorial, set up a new Juju model named `discourse`:
+To be able to work inside the Multipass VM first you need to log in with the following command:
+```
+multipass shell my-juju-vm
+```
+
+### Add a Juju model for the tutorial
+
+To easily clean up the resources and separate your workload from the contents of this tutorial, set up a new Juju model named `discourse-tutorial`:
 
 ```
-juju add-model discourse
+juju add-model discourse-tutorial
 ```
 
 ### Deploy the charms
@@ -38,11 +51,10 @@ juju deploy discourse-k8s
 
 Enable the required PostgreSQL extensions:
 ```
-juju config postgresql-k8s plugin_hstore_enable=True
-juju config postgresql-k8s plugin_pg_trgm_enable=True
+juju config postgresql-k8s plugin_hstore_enable=True plugin_pg_trgm_enable=True
 ```
 
-### Integrate the charms
+### Integrate with the Redis k8s charm the PostgreSQL k8s charm
 
 Integrate `redis-k8s` and `postgresql-k8s` to `discourse-k8s`:
 ```
@@ -52,48 +64,62 @@ juju integrate discourse-k8s postgresql-k8s
 
 By running `juju status --relations` the current state of the deployment can be queried:
 ```
-Model      Controller  Cloud/Region        Version  SLA          Timestamp
-discourse  microk8s    microk8s/localhost  3.1.7    unsupported  12:48:02+02:00
+Model               Controller  Cloud/Region        Version  SLA          Timestamp
+discourse-tutorial  microk8s    microk8s/localhost  3.5.4    unsupported  14:07:18+03:00
 
-App             Version  Status  Scale  Charm           Channel      Rev  Address         Exposed  Message
-discourse-k8s   3.2.0    active      1  discourse-k8s   stable        95  10.152.183.175  no       
-postgresql-k8s  14.10    active      1  postgresql-k8s  14/stable    193  10.152.183.59   no       
-redis-k8s       7.0.4    active      1  redis-k8s       latest/edge   27  10.152.183.46   no       
+App             Version  Status  Scale  Charm           Channel        Rev  Address         Exposed  Message
+discourse-k8s   3.3.0    active      1  discourse-k8s   latest/stable  173  10.152.183.231  no
+postgresql-k8s  14.12    active      1  postgresql-k8s  14/stable      381  10.152.183.143  no
+redis-k8s       7.2.5    active      1  redis-k8s       latest/edge     36  10.152.183.188  no
 
 Unit               Workload  Agent  Address      Ports  Message
-discourse-k8s/0*   active    idle   10.1.44.214         
-postgresql-k8s/0*  active    idle   10.1.44.219         
-redis-k8s/0*       active    idle   10.1.44.227         
+discourse-k8s/0*   active    idle   10.1.32.182
+postgresql-k8s/0*  active    idle   10.1.32.184         Primary
+redis-k8s/0*       active    idle   10.1.32.181
 
 Integration provider           Requirer                       Interface          Type     Message
-discourse-k8s:restart          discourse-k8s:restart          rolling_op         peer     
-postgresql-k8s:database        discourse-k8s:database         postgresql_client  regular  
-postgresql-k8s:database-peers  postgresql-k8s:database-peers  postgresql_peers   peer     
-postgresql-k8s:restart         postgresql-k8s:restart         rolling_op         peer     
-postgresql-k8s:upgrade         postgresql-k8s:upgrade         upgrade            peer     
-redis-k8s:redis                discourse-k8s:redis            redis              regular  
-redis-k8s:redis-peers          redis-k8s:redis-peers          redis-peers        peer     
+discourse-k8s:restart          discourse-k8s:restart          rolling_op         peer
+postgresql-k8s:database        discourse-k8s:database         postgresql_client  regular
+postgresql-k8s:database-peers  postgresql-k8s:database-peers  postgresql_peers   peer
+postgresql-k8s:restart         postgresql-k8s:restart         rolling_op         peer
+postgresql-k8s:upgrade         postgresql-k8s:upgrade         upgrade            peer
+redis-k8s:redis                discourse-k8s:redis            redis              regular
+redis-k8s:redis-peers          redis-k8s:redis-peers          redis-peers        peer
 ```
 The deployment finishes when all the charms show `Active` states.
 
-Run `kubectl get pods -n discourse` to see the pods that are being created by the charms:
+Run `kubectl get pods -n discourse-tutorial` to see the pods that are being created by the charms:
 ```
 NAME                             READY   STATUS    RESTARTS   AGE
-modeloperator-64c58d675d-csj47   1/1     Running   0          5m30s
+modeloperator-c584f6f9f-qf9gr    1/1     Running   0          5m30s
 redis-k8s-0                      3/3     Running   0          5m22s
 discourse-k8s-0                  2/2     Running   0          5m1s
 postgresql-k8s-0                 2/2     Running   0          5m9s
 ```
 
-### Provide ingress capabilities 
+### Provide ingress capabilities
 
 In order to expose the charm, the Nginx Ingress Integrator needs to be deployed and integrated with Discourse:
 
 ```
 juju deploy nginx-ingress-integrator
-# If your cluster has RBAC enabled you'll be prompted to run the following:
-juju trust nginx-ingress-integrator --scope=cluster
+```
+To check if RBAC is enabled run the following command:
+```
+microk8s status | grep rbac
+```
+If it is enabled, then the output should be like the following:
+```
+rbac                 # (core) Role-Based Access Control for authorisation
+```
+If the output is empty then RBAC is not enabled.
 
+If your cluster has RBAC enabled, you'll be prompted to run the following command:
+```
+juju trust nginx-ingress-integrator --scope=cluster
+```
+Then you need to integrate the charm with Nginx Ingress Integrator:
+```
 juju integrate discourse-k8s nginx-ingress-integrator
 ```
 
@@ -103,7 +129,9 @@ To create an admin user, use the `create-user` action:
 ```
 juju run discourse-k8s/0 create-user admin=true email=email@example.com
 ```
-The command will return the password of the created user. Discourse will be deployed with `discourse-k8s` as default hostname. In order to reach it, modify your `/etc/hosts` file so that it points to `127.0.0.1`:
+The command will return the password of the created user. Discourse will be deployed with `discourse-k8s` as default hostname.
+
+If you are following the tutorial in your local machine, modify your `/etc/hosts` file so that it points to `127.0.0.1`:
 
 ```
 echo 127.0.0.1 discourse-k8s >> /etc/hosts
@@ -111,11 +139,16 @@ echo 127.0.0.1 discourse-k8s >> /etc/hosts
 
 After that, visit `http://discourse-k8s` to reach Discourse, using the credentials returned from the `create-user` action to login.
 
-### Clean up the environment 
+### Clean up the environment
 
-Congratulations! You have successfully finished the Discourse tutorial. You can now remove the 
+Congratulations! You have successfully finished the Discourse tutorial. You can now remove the
 model environment that you've created using the following command:
 
 ```
-juju destroy-model discourse --destroy-storage
-```
\ No newline at end of file
+juju destroy-model discourse-tutorial --destroy-storage
+```
+If you used Multipass, to remove the Multipass instance you created for this tutorial, use the following command.
+```
+multipass delete --purge my-juju-vm
+```
+Finally, remove the `127.0.0.1 discourse-k8s` line from the `/etc/hosts` file.
\ No newline at end of file