modified: docs/how-to/configure-s3.md,docs/how-to/access--the-rails-c…

…onsole.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

@@ -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.

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`.

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).

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).

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).

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.

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)

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`
+Redis integrate commands: 
+```
+juju integrate discourse-k8s redis-k8s
+```

docs/tutorial.md

@@ -118,4 +118,4 @@ model environment that you've created using the following command:
 
 ```
 juju destroy-model discourse --destroy-storage
-```
+```