diff --git a/docs/explanation/e-architecture.md b/docs/explanation/e-architecture.md
new file mode 100644
index 0000000000..25beb72f43
--- /dev/null
+++ b/docs/explanation/e-architecture.md
@@ -0,0 +1,127 @@
+# Architecture
+
+[PostgreSQL](https://www.postgresql.org/) is one of the most popular open source database. The “[Charmed PostgreSQL](https://charmhub.io/postgresql)” is a Juju-based operator to deploy and support PostgreSQL from [day 0 to day 2](https://codilime.com/blog/day-0-day-1-day-2-the-software-lifecycle-in-the-cloud-age/), it is based on the [PostgreSQL Community Edition](https://www.postgresql.org/community/) using the [Patroni](https://github.com/zalando/patroni) to manage PostgreSQL cluster based on [PostgreSQL synchronous replication](https://patroni.readthedocs.io/en/latest/replication_modes.html#postgresql-synchronous-replication).
+
+![image|690x423, 100%](upload://fqMd5JlHeegw0PlUjhWKRu858Nc.png)
+
+
+## HLD (High Level Design)
+
+The charm design leverages on the SNAP “[charmed-postgresql](https://snapcraft.io/charmed-postgresql)” which is deployed by Juju on the specified VM/MAAS/bare-metal machine based on Ubuntu Jammy/22.04. SNAP allows to run PostgreSQL service(s) in a secure and isolated environment ([strict confinement](https://ubuntu.com/blog/demystifying-snap-confinement)). The installed SNAP:
+```
+> juju ssh postgresql/0 snap list charmed-postgresql
+Name Version Rev Tracking Publisher Notes
+charmed-postgresql 14.9 70 latest/stable dataplatformbot held
+```
+
+The SNAP ships the following components:
+
+* PostgreSQL (based on Ubuntu APT package "[postgresql](https://packages.ubuntu.com/jammy/postgresql)")
+* PgBouncer (based on Canonical [backport](https://launchpad.net/~data-platform/+archive/ubuntu/pgbouncer))
+* Patroni (based on Canonical [backport](https://launchpad.net/~data-platform/+archive/ubuntu/patroni))
+* pgBackRest (based on Canonical [backport](https://launchpad.net/~data-platform/+archive/ubuntu/pgbackrest))
+* Prometheus PostgreSQL Exporter (based on Canonical [backport](https://launchpad.net/~data-platform/+archive/ubuntu/postgres-exporter))
+* Prometheus PgBouncer Exporter (based on Canonical [backport](https://launchpad.net/~data-platform/+archive/ubuntu/pgbouncer-exporter))
+* Prometheus Grafana dashboards and Loki alert rules are part of the charm revision (and missing in SNAP).
+
+Versions of all the components above are carefully chosen to fit functionality of each other.
+
+The Charmed PostgreSQL unit consisting of a several services which are enabled/activated accordingly to the setup:
+
+```
+> juju ssh postgresql/0 snap services charmed-postgresql
+Service Startup Current Notes
+charmed-postgresql.patroni enabled active -
+charmed-postgresql.pgbackrest-service enabled active -
+charmed-postgresql.prometheus-postgres-exporter enabled active -
+
+```
+
+The `patroni` snap service is a main PostgreSQL instance which is normally up and running right after the charm deployment.
+
+The `pgbackrest` snap service is a backup framework for PostgreSQL. It is disabled if [Backup](/t/9683) is not configured.
+
+The `prometheus-postgres-exporter` service is activated after the relation with [COS Monitoring](/t/10600) only.
+
+> **:information_source: Note:** it is possible to star/stop/restart snap services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!
+
+> **:warning: Important:** all snap resources must be executed under the special user `snapd_daemon` only!
+
+The snap "charmed-postgresql" also ships list of tools used by charm:
+* `charmed-postgresql.psql` (alias `psq`) - is PostgreSQL interactive terminal.
+* `charmed-postgresql.patronictl` - a tool to monitor and manage Patroni.
+* `charmed-postgresql.pgbackrest` - a tool to backup/restore PostgreSQL DB.
+
+
+## Integrations
+
+### PgBouncer
+
+[PgBouncer](http://www.pgbouncer.org/) is a lightweight connection pooler for PostgreSQL that provides transparent routing between your application and back-end PostgreSQL Servers. The "[PgBouncer](https://charmhub.io/pgbouncer)" is an independent charm "Charmed PostgreSQL" can be related with.
+
+### TLS Certificates Operator
+
+[TLS Certificates](https://charmhub.io/tls-certificates-operator) charm responsible for distributing certificates through relationship. Certificates are provided by the operator through Juju configs. For the playground deployments, the [self-signed operator](https://charmhub.io/self-signed-certificates) is available as well.
+
+### S3 Integrator
+
+[S3 Integrator](https://charmhub.io/s3-integrator) is an integrator charm for providing S3 credentials to Charmed PostgreSQL which seek to access shared S3 data. Store the credentials centrally in the integrator charm and relate consumer charms as needed.
+
+### Data Integrator
+
+[Data Integrator](https://charmhub.io/data-integrator) charm is a solution to request DB credentials for non-native Juju applications. Not all applications implement a data_interfaces relation but allow setting credentials via config. Also, some of the applications are run outside of juju. This integrator charm allows receiving credentials which can be passed into application config directly without implementing juju-native relation.
+
+### PostgreSQL Test App
+
+The charm "[PostgreSQL Test App](https://charmhub.io/postgresql-test-app)" is a Canonical test application to validate the charm installation / functionality and perform the basic performance tests.
+
+### Grafana
+
+Grafana is an open-source visualization tools that allows to query, visualize, alert on, and visualize metrics from mixed datasources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/t/10600) setup.
+
+### Loki
+
+Loki is an open-source fully-featured logging system. This charms is shipped with support for the [Loki Operator](https://charmhub.io/loki-k8s) to collect the generated logs. Please follow [COS Monitoring](/t/10600) setup.
+
+### 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 exporters, alerts and support for integrating with the [Prometheus Operator](https://charmhub.io/prometheus-k8s) to automatically scrape the targets. Please follow [COS Monitoring](/t/10600) setup.
+
+
+## LLD (Low Level Design)
+
+Please check the charm state machines displayed on [workflow diagrams](/t/9305). The low-level logic is mostly common for both VM and K8s charms.
+
+
+
+### 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. [on_install](https://juju.is/docs/sdk/install-event): install the snap "charmed-postgresql" and perform basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster).
+2. [leader-elected](https://juju.is/docs/sdk/leader-elected-event): generate all the secrets to bootstrap the cluster.
+3. [leader-settings-changed](https://juju.is/docs/sdk/leader-settings-changed-event): Handle the leader settings changed event.
+4. [start](https://juju.is/docs/sdk/start-event): Init/setting up the cluster node.
+5. [config_changed](https://juju.is/docs/sdk/config-changed-event): usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
+6. [update-status](https://juju.is/docs/sdk/update-status-event): Takes care of workload health checks.
+
+
+### Charm Code Overview
+
+The "[src/charm.py](https://github.com/canonical/postgresql-operator/blob/main/src/charm.py)" is the default entry point for a charm and has the `PostgresqlOperatorCharm` 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 VM and K8s charm flavors shares the codebase via [charm libraries](https://juju.is/docs/sdk/libraries) in [lib/charms/postgresql_k8s/v0/](https://github.com/canonical/postgresql-k8s-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py) (of K8s flavor of the charm!):
+```
+> charmcraft list-lib postgresql-k8s
+Library name API Patch
+postgresql 0 12
+postgresql_tls 0 7
+```
\ No newline at end of file
diff --git a/docs/explanation/e-interfaces-endpoints.md b/docs/explanation/e-interfaces-endpoints.md
new file mode 100644
index 0000000000..798986ff23
--- /dev/null
+++ b/docs/explanation/e-interfaces-endpoints.md
@@ -0,0 +1,48 @@
+# Interfaces/endpoints
+
+The charm supports modern `postgresql_client` and legacy `pgsql` interfaces (in a backward compatible mode).
+
+**Note:** do NOT relate both modern and legacy interfaces simultaneously!
+
+## Modern interfaces
+
+This charm provides modern ['postgresql_client' interface](https://github.com/canonical/charm-relation-interfaces). Applications can easily connect PostgreSQL using ['data_interfaces' ](https://charmhub.io/data-platform-libs/libraries/data_interfaces) library from ['data-platform-libs'](https://github.com/canonical/data-platform-libs/).
+
+### Modern `postgresql_client` interface (`database` endpoint):
+
+Adding a relation is accomplished with `juju relate` (or `juju integrate` for Juju 3.x) via endpoint `database`. Example:
+
+```shell
+# Deploy Charmed PostgreSQL cluster with 3 nodes
+juju deploy postgresql -n 3 --channel 14
+
+# Deploy the relevant application charms
+juju deploy mycharm
+
+# Relate PostgreSQL with your application
+juju relate postgresql:database mycharm:database
+
+# Check established relation (using postgresql_client interface):
+juju status --relations
+
+# Example of the properly established relation:
+# > Relation provider Requirer Interface Type
+# > postgresql:database mycharm:database postgresql_client regular
+```
+
+Find all details about default and extra DB user roles in "[Charm Users explanations](/t/10798)".
+
+## Legacy interfaces
+
+**Note:** Legacy relations are deprecated and will be discontinued on future releases. Usage should be avoided. Check the legacy interfaces implementation limitations in the "[Legacy charm](/t/10690)" document.
+
+### Legacy `pgsql` interface (`db` and `db-admin` endpoints):
+
+This charm supports legacy interface `pgsql` from the previous [PostgreSQL charm](https://launchpad.net/postgresql-charm):
+
+```shell
+juju relate postgresql:db mailman3-core
+juju relate postgresql:db-admin landscape-server
+```
+
+**Note:** The endpoint `db-admin` provides the same legacy interface `pgsql` with PostgreSQL admin-level privileges. It is NOT recommended to use it from security point of view.
\ No newline at end of file
diff --git a/docs/explanation/e-juju-details.md b/docs/explanation/e-juju-details.md
new file mode 100644
index 0000000000..65f3b702cd
--- /dev/null
+++ b/docs/explanation/e-juju-details.md
@@ -0,0 +1,43 @@
+# Juju tech details
+
+[Juju](https://juju.is/) is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management of applications at any scale, on any infrastructure using charms.
+
+This [charm](https://charmhub.io/postgresql) is an operator - business logic encapsulated in reusable software packages that automate every aspect of an application's life. Charms are shared via [CharmHub](https://charmhub.io/).
+
+See also:
+
+* [Juju Documentation](https://juju.is/docs/juju) and [Blog](https://ubuntu.com/blog/tag/juju)
+* [Charm SDK](https://juju.is/docs/sdk)
+
+## Breaking changes between Juju 2.9.x and 3.x
+
+As this charm documentation is written for Juju 3.x, users of 2.9.x will encounter noteworthy changes when following the instructions. This section explains those changes.
+
+Breaking changes have been introduced in the Juju client between versions 2.9.x and 3.x. These are caused by the renaming and re-purposing of several commands - functionality and command options remain unchanged.
+
+In the context of this guide, the pertinent changes are shown here:
+
+|2.9.x|3.x|
+| --- | --- |
+|**add-relation**|**integrate**|
+|**relate**|**integrate**|
+|**run**|**exec**|
+|**run-action --wait**|**run**|
+
+See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022) for the comprehensive list of changes.
+
+The response is to therefore substitute the documented command with the equivalent 2.9.x command. For example:
+
+### Juju 3.x:
+```shell
+juju integrate postgresql:database postgresql-test-app
+
+juju run postgresql/leader get-password
+```
+### Juju 2.9.x:
+```shell
+juju relate postgresql:database postgresql-test-app
+
+juju run-action --wait postgresql/leader get-password
+```
+> :tipping_hand_man: [The document based on OpenStack guide.](https://docs.openstack.org/charm-guide/latest/project/support-notes.html#breaking-changes-between-juju-2-9-x-and-3-x)
\ No newline at end of file
diff --git a/docs/explanation/e-legacy-charm.md b/docs/explanation/e-legacy-charm.md
new file mode 100644
index 0000000000..f99cc473c4
--- /dev/null
+++ b/docs/explanation/e-legacy-charm.md
@@ -0,0 +1,84 @@
+## Charm types "legacy" vs "modern"
+There are [two types of charms](https://juju.is/docs/sdk/charm-taxonomy#heading--charm-types-by-generation) stored under the same charm name `postgresql`:
+
+1. [Reactive](https://juju.is/docs/sdk/charm-taxonomy#heading--reactive) charm in the channel `latest/stable` (called `legacy`)
+2. [Ops-based](https://juju.is/docs/sdk/ops) charm in the channel `14/stable` (called `modern`)
+
+The legacy charm provided endpoints `db` and `db-admin` (for the interface `pgsql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `postgresql_client`). Read more details about the available [endpoints/interfaces](https://charmhub.io/postgresql/docs/e-interfaces).
+
+**Note**: Please choose one endpoint to use. No need to relate all of them simultaneously!
+
+## The default track "latest" vs "14"
+
+The [default track](https://docs.openstack.org/charm-guide/yoga/project/charm-delivery.html) has been switched from the `latest` to `14`. It is [to ensure](https://discourse.charmhub.io/t/request-switch-default-track-from-latest-to-14-for-postgresql-k8s-charms/10314) all new deployments use a modern codebase. We strongly advise against using the latest track due to its implicit nature. In doing so, a future charm upgrade may result in a PostgreSQL version incompatible with an integrated application. Track 14 guarantees PostgreSQL 14 deployment only. The track `latest` will be closed after all applications migrated from Reactive to Ops-based charm.
+
+
+## How to migrate from "legacy" to "modern" charm
+
+The "modern" charm provides temporary support for the legacy interfaces:
+
+* **quick try**: relate the current application with new charm using endpoint `db` (set the channel to `14/stable`). No extra changes necessary:
+
+```
+ postgresql:
+ charm: postgresql
+ channel: 14/stable
+```
+
+* **proper migration**: migrate the application to the new interface "[postgresql_client](https://github.com/canonical/charm-relation-interfaces)". The application will connect PostgreSQL using "[data_interfaces](https://charmhub.io/data-platform-libs/libraries/data_interfaces)" library from "[data-platform-libs](https://github.com/canonical/data-platform-libs/)" via endpoint `database`.
+
+**Warning**: NO in-place upgrades possible! Reactive charm cannot be upgraded to Operator-framework-based one. To move DB data, the second/modern DB application must be launched nearby and data should be copied from "legacy" application to the "modern" one. Canonical Data Platform team is preparing copy&paste guide right now. Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need migration instructions.
+
+**Note**: the `trust` option must be enabled if [ Role Based Access Control (RBAC)](https://kubernetes.io/docs/concepts/security/rbac-good-practices/) is in use on your Kubernetes.
+
+## How to deploy old "legacy" postgresql charm
+
+Deploy the charm using the channel `latest/stable`:
+
+```
+ postgresql:
+ charm: postgresql
+ channel: latest/stable
+```
+
+**Note**: remove Charm store prefix `cs:` from the bundle. Otherwise the modern charm will be chosen by Juju (due to the default track pointing to `14/stable` and not `latest/stable`). The common error message is: `cannot deploy application "postgresql": unknown option "..."`.
+
+## Config options supported by modern charm
+
+The legacy charm config options were not moved to the modern charm due to no need. The modern charm applies the best possible configuration automatically.
+
+Feel free to [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) about the DB tuning/config options.
+
+## Extensions supported by modern charm
+
+The legacy charm provided plugins/extensions enabling through the relation (interface `pgsql`). It is NOT supported by the modern charm (neither `pgsql` nor `postgresql_client` interfaces). Please enable the necessary extensions using appropriate `plugin_*_enable` [config option](https://charmhub.io/postgresql/configure) of the modern charm. After enabling the modern charm, it will provide plugins support for both `pgsql` and `postgresql_client` interfaces.
+
+Please find the list of supported PostgreSQL [Extensions](/t/10946) by modern charm.
+
+Feel free to [contact us](/t/11863) with a list of required extensions.
+
+## Roles supported by modern charm
+
+In the legacy charm, the user could request roles by setting the `roles` field to a comma separated list of desired roles. It is NOT supported by the modern charm implementation of the legacy `pgsql` interface. The same functionality is provided via the modern `postgresql_client` using "[extra-user-roles](/t/10798#extra-user-roles)".
+
+For more information about migrating the new interface, see [this guide](/t/11865).
+
+## Supported PostgreSQL versions by modern charm
+
+At the moment, the modern charms support PostgreSQL 14 (based on Jammy/22.04 series) only.
+
+Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need different versions/series.
+
+## Supported architectures
+
+Currently, the charm supports architecture `amd64` (all revisions) and `arm64` (from revision 396+).
+
+See the technical details in [Supported architectures](/t/11743).
+
+## How to report issues and contact authors
+
+The "legacy charm" (from `latest/stable`) is stored on [Launchpad](https://git.launchpad.net/postgresql-charm/), here is the link to report all [legacy charm issues](https://bugs.launchpad.net/postgresql-charm).
+
+The "modern charm" (from `14/stable`) is stored on [GitHub](https://github.com/canonical/postgresql-operator), here is the link to report [modern charm issues](https://github.com/canonical/postgresql-operator/issues/new/choose).
+
+Do you have questions? [Contact us](/t/11863)!
\ No newline at end of file
diff --git a/docs/explanation/e-logs.md b/docs/explanation/e-logs.md
new file mode 100644
index 0000000000..247501667e
--- /dev/null
+++ b/docs/explanation/e-logs.md
@@ -0,0 +1,93 @@
+# Logs
+
+The list of all the charm components are well described in the "[Architecture](/t/11857)".
+It is a dedicated section to highlight logs for each component to simplify troubleshooting.
+
+## Core logs
+
+PostgreSQL and Patroni logs can be found in `/var/snap/charmed-postgresql/common/var/log/postgresql` and `/var/snap/charmed-postgresql/common/var/log/patroni` respectively:
+```shell
+> ls -alh /var/snap/charmed-postgresql/common/var/log/postgresql
+total 20K
+drwxr-xr-x 2 snap_daemon root 4.0K Oct 11 15:09 .
+drwxr-xr-x 6 snap_daemon root 4.0K Oct 11 15:04 ..
+-rw------- 1 snap_daemon snap_daemon 4.3K Oct 11 15:05 postgresql-3_1505.log
+-rw------- 1 snap_daemon snap_daemon 0 Oct 11 15:06 postgresql-3_1506.log
+-rw------- 1 snap_daemon snap_daemon 0 Oct 11 15:07 postgresql-3_1507.log
+-rw------- 1 snap_daemon snap_daemon 817 Oct 11 15:08 postgresql-3_1508.log
+-rw------- 1 snap_daemon snap_daemon 0 Oct 11 15:09 postgresql-3_1509.log
+```
+```shell
+> ls -alh /var/snap/charmed-postgresql/common/var/log/patroni/
+total 28K
+drwxr-xr-x 2 snap_daemon root 4.0K Oct 11 15:29 .
+drwxr-xr-x 6 snap_daemon root 4.0K Oct 11 15:25 ..
+-rw-r--r-- 1 snap_daemon snap_daemon 356 Oct 11 15:29 patroni.log
+-rw-r--r-- 1 snap_daemon snap_daemon 534 Oct 11 15:28 patroni.log.1
+-rw-r--r-- 1 snap_daemon snap_daemon 520 Oct 11 15:27 patroni.log.2
+-rw-r--r-- 1 snap_daemon snap_daemon 584 Oct 11 15:27 patroni.log.3
+-rw-r--r-- 1 snap_daemon snap_daemon 464 Oct 11 15:27 patroni.log.4
+```
+The PostgreSQL log naming convention is `postgresql-_.log`. The log message format is ` UTC []: : `. E.g:
+```shell
+> cat /var/snap/charmed-postgresql/common/var/log/postgresql/postgresql-3_1508.log
+2023-10-11 15:08:17 GMT [4338]: user=,db=,app=,client=,line=8 LOG: received SIGHUP, reloading configuration files
+2023-10-11 15:08:17 GMT [4338]: user=,db=,app=,client=,line=9 LOG: parameter "archive_command" changed to "pgbackrest --config=/var/snap/charmed-postgresql/current/etc/pgbackrest/pgbackrest.conf --stanza=pg.pg archive-push %p"
+2023-10-11 15:08:21 GMT [9435]: user=backup,db=postgres,app=pgBackRest [check],client=[local],line=1 LOG: restore point "pgBackRest Archive Check" created at 0/19A86D0
+2023-10-11 15:08:21 GMT [9435]: user=backup,db=postgres,app=pgBackRest [check],client=[local],line=2 STATEMENT: select pg_catalog.pg_create_restore_point('pgBackRest Archive Check')::text
+2023-10-11 15:08:27 GMT [4338]: user=,db=,app=,client=,line=10 LOG: received SIGHUP, reloading configuration files
+```
+
+The Patroni log message format is ` UTC []: : `. E.g:
+```shell
+> cat /var/snap/charmed-postgresql/common/var/log/patroni/patroni.log.4
+2023-10-11 15:27:01 UTC [4247]: WARNING: Could not activate Linux watchdog device: "Can't open watchdog device: [Errno 2] No such file or directory: '/dev/watchdog'"
+2023-10-11 15:27:01 UTC [4247]: INFO: initialized a new cluster
+2023-10-11 15:27:01 UTC [4247]: INFO: no action. I am (pg2-0), the leader with the lock
+2023-10-11 15:27:11 UTC [4247]: INFO: No local configuration items changed.
+2023-10-11 15:27:11 UTC [4247]: INFO: Changed archive_mode from on to True (restart might be required)
+2023-10-11 15:27:11 UTC [4247]: INFO: Changed synchronous_commit from on to True
+```
+
+All timestamps are in UTC.
+
+## Optional logs
+
+If S3 backups are enabled, Pgbackrest logs would be located in `/var/snap/charmed-postgresql/common/var/log/pgbackrest`:
+```shell
+> ls -alh /var/snap/charmed-postgresql/common/var/log/pgbackrest/
+total 20K
+drwxr-xr-x 2 snap_daemon root 4.0K Oct 11 15:14 .
+drwxr-xr-x 6 snap_daemon root 4.0K Oct 11 15:04 ..
+-rw-r----- 1 snap_daemon snap_daemon 1.7K Oct 11 15:14 pg.pg-backup.log
+-rw-r----- 1 snap_daemon snap_daemon 717 Oct 11 15:14 pg.pg-expire.log
+-rw-r----- 1 snap_daemon snap_daemon 859 Oct 11 15:08 pg.pg-stanza-create.log
+```
+
+The naming convention of the Pgbackrest logs is `.patroni--.log`. Log output should look similar to:
+```shell
+> cat /var/snap/charmed-postgresql/common/var/log/pgbackrest/pg.pg-expire.log
+-------------------PROCESS START-------------------
+2023-10-11 15:14:44.555 P00 INFO: expire command begin 2.47: --config=/var/snap/charmed-postgresql/current/etc/pgbackrest/pgbackrest.conf --exec-id=11725-9ad622c8 --lock-path=/tmp --log-level-console=debug --log-path=/var/snap/charmed-postgresql/common/var/log/pgbackrest --repo1-path=/postgresql-test2 --repo1-retention-full=9999999 --repo1-s3-bucket=dragop-test-bucket --repo1-s3-endpoint=https://s3.eu-central-1.amazonaws.com --repo1-s3-key= --repo1-s3-key-secret= --repo1-s3-region=eu-central-1 --repo1-s3-uri-style=host --repo1-type=s3 --stanza=pg.pg
+2023-10-11 15:14:44.983 P00 INFO: expire command end: completed successfully (428ms)
+root@juju-7bca0e-3:~# cat /var/snap/charmed-postgresql/common/var/log/pgbackrest/pg.pg-backup.log
+-------------------PROCESS START-------------------
+2023-10-11 15:13:17.217 P00 INFO: backup command begin 2.47: --no-backup-standby --config=/var/snap/charmed-postgresql/current/etc/pgbackrest/pgbackrest.conf --exec-id=11725-9ad622c8 --lock-path=/tmp --log-level-console=debug --log-path=/var/snap/charmed-postgresql/common/var/log/pgbackrest --pg1-path=/var/snap/charmed-postgresql/common/var/lib/postgresql --pg1-socket-path=/tmp --pg1-user=backup --repo1-path=/postgresql-test2 --repo1-retention-full=9999999 --repo1-s3-bucket=dragop-test-bucket --repo1-s3-endpoint=https://s3.eu-central-1.amazonaws.com --repo1-s3-key= --repo1-s3-key-secret= --repo1-s3-region=eu-central-1 --repo1-s3-uri-style=host --repo1-type=s3 --stanza=pg.pg --start-fast --type=full
+2023-10-11 15:13:18.269 P00 INFO: execute non-exclusive backup start: backup begins after the requested immediate checkpoint completes
+2023-10-11 15:13:19.370 P00 INFO: backup start archive = 000000010000000000000003, lsn = 0/3000028
+2023-10-11 15:13:19.370 P00 INFO: check archive for prior segment 000000010000000000000002
+2023-10-11 15:14:40.970 P00 INFO: execute non-exclusive backup stop and wait for all WAL segments to archive
+2023-10-11 15:14:41.273 P00 INFO: backup stop archive = 000000010000000000000003, lsn = 0/3000138
+2023-10-11 15:14:41.641 P00 INFO: check archive for segment(s) 000000010000000000000003:000000010000000000000003
+2023-10-11 15:14:42.478 P00 INFO: new backup label = 20231011-151318F
+2023-10-11 15:14:44.555 P00 INFO: full backup size = 25.9MB, file total = 956
+2023-10-11 15:14:44.555 P00 INFO: backup command end: completed successfully (87340ms)
+```
+
+## Logs rotation
+
+Charmed PostgreSQL is configured to rotate PostgreSQL text logs every minute and Patroni logs approximately every minute and both are to retain a week's worth of logs.
+
+For PostgreSQL, logs will be truncated when the week turns and the same minute of the same hour of the same weekday comes to pass. E.g. at 12:01 UTC on Monday either a new log file will be created or last week's log will be overwritten.
+
+Due to Patroni only supporting size based rotation, it has been configured to retain logs for a comparatively similar timeframe as PostgreSQL. The assumed size of a minute of Patroni logs is 600 bytes, but the estimation is bound to be imprecise. Patroni will retain 10,080 log files (for every minute of a week). The current log is `patroni.log`, when rotating Patroni will append a number to the name of the file and remove logs over the limit.
\ No newline at end of file
diff --git a/docs/explanation/e-statuses.md b/docs/explanation/e-statuses.md
new file mode 100644
index 0000000000..42eb58c05f
--- /dev/null
+++ b/docs/explanation/e-statuses.md
@@ -0,0 +1,21 @@
+# Charm Statuses Explanations
+
+> :warning: **WARNING** : it is an work-in-progress article. Do NOT use it in production! Contact [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in the topic.
+
+The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#heading--application-status). Here you can find the expected end-users reaction on different statuses:
+
+| Juju Status | Message | Expectations | Actions |
+|-------|-------|-------|-------|
+| **active** | any | Normal charm operations | No actions required |
+| **waiting** | any | Charm is waiting for relations to be finished | No actions required |
+| **maintenance** | any | Charm is performing the internal maintenance (e.g. cluster re-configuration, upgrade, ...) | No actions required |
+| **blocked** | failed to update cluster members on member | TODO: error/retry? | |
+| **blocked** | failed to install snap packages | There are issues with the network connection and/or the Snap Store | Check your internet connection and https://status.snapcraft.io/. Remove the application and when everything is ok, deploy the charm again |
+| **blocked** | failed to patch snap seccomp profile | The charm failed to patch one issue that happens when pgBackRest restores a backup (this blocked status should be removed when https://github.com/pgbackrest/pgbackrest/releases/tag/release%2F2.46 is added to the snap) | Remove the unit and add it back again |
+| **blocked** | failed to set up postgresql_exporter options | The charm failed to set up the metrics exporter | Remove the unit and add it back again |
+| **blocked** | failed to start Patroni | TODO: error/retry? | |
+| **blocked** | Failed to create postgres user | The charm couldn't create the default `postgres` database user due to connection problems | Connect to the database using the `operator` user and the password from the `get-password` action, then run `CREATE ROLE postgres WITH LOGIN SUPERUSER;` |
+| **blocked** | Failed to restore backup | The database couldn't start after the restore | The charm needs fix in the code to recover from this status and enable a new restore to be requested |
+| **error** | any | An unhanded internal error happened | Read the message hint. Execute `juju resolve ` after addressing the root of the error state |
+| **terminated** | any | The unit is gone and will be cleaned by Juju soon | No actions possible |
+| **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: K8s charm termination in progress. | Manual investigation required if status is permanent |
\ No newline at end of file
diff --git a/docs/explanation/e-users.md b/docs/explanation/e-users.md
new file mode 100644
index 0000000000..2a2c85d186
--- /dev/null
+++ b/docs/explanation/e-users.md
@@ -0,0 +1,102 @@
+# Charm Users explanations
+
+There are two types of users in PostgreSQL:
+* Internal users (used by charm operator)
+* Relation/integration users (used by related applications)
+ * Extra user roles (if default permissions are not enough)
+
+
+## Internal users explanations:
+
+The operator uses the following internal DB users:
+
+* `postgres` - the [initial/default](https://charmhub.io/postgresql/docs/t-manage-passwords) PostgreSQL user. Used for very initial bootstrap only.
+* `operator` - the user that charm.py uses to manage database/cluster.
+* `replication` - the user performs replication between database PostgreSQL cluster members.
+* `rewind` - the internal user for synchronizing a PostgreSQL cluster with another copy of the same cluster.
+* `monitoring` - the user for [COS integration](https://charmhub.io/postgresql/docs/h-enable-monitoring).
+* `backups` - the user to [perform/list/restore backups](https://charmhub.io/postgresql/docs/h-create-and-list-backups).
+
+The full list of internal users is available in charm [source code](https://github.com/canonical/postgresql-operator/blob/main/src/constants.py). The full dump of internal users (on the newly installed charm):
+
+```shell
+postgres=# \du
+ List of roles
+ Role name | Attributes | Member of
+-------------+------------------------------------------------------------+--------------
+ backup | Superuser | {}
+ monitoring | | {pg_monitor}
+ operator | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
+ postgres | Superuser | {}
+ replication | Replication | {}
+ rewind | | {}
+```
+**Note**: it is forbidden to use/manage described above users! They are dedicated to the operators logic! Please use [data-integrator](https://charmhub.io/postgresql/docs/t-integrations) charm to generate/manage/remove an external credentials.
+
+It is allowed to rotate passwords for *internal* users using action 'set-password':
+```shell
+> juju show-action postgresql set-password
+Change the system user's password, which is used by charm. It is for internal charm users and SHOULD NOT be used by applications.
+
+Arguments
+password:
+ type: string
+ description: The password will be auto-generated if this option is not specified.
+username:
+ type: string
+ description: The username, the default value 'operator'. Possible values - operator, replication, rewind.
+```
+For example, to generate a new random password for *internal* user:
+
+```shell
+> juju run-action --wait postgresql/leader set-password username=operator
+
+unit-postgresql-1:
+ UnitId: postgresql/1
+ id: "2"
+ results:
+ password: k4qqnWSZJZrcMt4B
+ status: completed
+```
+To set a predefined password for the specific user, run:
+```shell
+> juju run-action --wait postgresql/leader set-password username=operator password=newpassword
+
+unit-postgresql-1:
+ UnitId: postgresql/1
+ id: "4"
+ results:
+ password: newpassword
+ status: completed
+```
+**Note**: the action `set-password` must be executed on juju leader unit (to update peer relation data with new value).
+
+
+## Relation/integration users explanations:
+
+The operator created a dedicated user for every application related/integrated with database. Those users are removed on the juju relation/integration removal request. However, DB data stays in place and can be reused on re-created relations (using new user credentials):
+
+```shell
+postgres=# \du
+ List of roles
+ Role name | Attributes | Member of
+-------------+------------------------------------------------------------+--------------
+ ..
+ relation-6 | | {}
+ relation-8 | | {}
+ ...
+```
+
+**Note**: If password rotation is needed for users used in relations, it is needed to remove the relation and create it again:
+```shell
+> juju remove-relation postgresql myclientapp
+> juju wait-for application postgresql
+> juju relate postgresql myclientapp
+```
+
+
+### Extra user roles
+
+When an application charm requests a new user through the relation/integration it can specify that the user should have the `admin` role in the `extra-user-roles` field. The `admin` role enables the new user to read and write to all databases (for the `postgres` system database it can only read data) and also to create and delete non-system databases.
+
+**Note**: `extra-user-roles` is supported by modern interface `postgresql_client` only and missing for legacy `pgsql` interface. Read more about the supported charm interfaces [here](/t/10251).
\ No newline at end of file
diff --git a/docs/how-to/h-async/h-async-integrate.md b/docs/how-to/h-async/h-async-integrate.md
new file mode 100644
index 0000000000..5707c5533b
--- /dev/null
+++ b/docs/how-to/h-async/h-async-integrate.md
@@ -0,0 +1,81 @@
+# Integrate with a client application
+[note type="caution"]
+This is an internal article. **Do not use it in production!**
+
+Contact the [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in this topic.
+[/note]
+
+This guide will show you how to integrate a client application with a cross-regional async setup using an example PostgreSQL deployment with two servers: one in Rome and one in Lisbon.
+
+## Prerequisites
+* `juju v.3.4.2+`
+* A cross-regional async replication setup
+ * Refer to the page [How to set up clusters](/t/13991)
+
+## Summary
+* [Configure database endpoints](#heading--configure-endpoints)
+* [Internal client](#heading--internal-client)
+* [External client](#heading--external-client)
+
+---
+
+
+
+To make your database available to a client application, you must first offer and consume database endpoints.
+
+### Offer database endpoints
+
+[Offer](https://juju.is/docs/juju/offer) the `database` endpoint on each of the `postgresql` applications.
+
+```shell
+juju switch rome
+juju offer db1:database db1database
+
+juju switch lisbon
+juju offer db2:database db2database
+```
+
+### Consume endpoints on client app
+
+It is good practice to use a separate model for the client application rather than using one of the database host models.
+
+```shell
+juju add-model app
+juju switch app
+juju consume rome.db1database
+juju consume lisbon.db2database
+```
+
+ Internal client
+
+If the client application is another charm, deploy them and connect them with `juju integrate`.
+
+
+
+```shell
+juju switch app
+
+juju deploy postgresql-test-app
+juju deploy pgbouncer --channel 1/stable
+
+juju integrate postgresql-test-app:first-database pgbouncer
+juju integrate pgbouncer db1database
+```
+
+ External client
+
+If the client application is external, they must be integrated via the [`data-integrator` charm](https://charmhub.io/data-integrator).
+
+
+
+```shell
+juju switch app
+
+juju deploy data-integrator --config database-name=mydatabase
+juju deploy pgbouncer pgbouncer-external --channel 1/stable
+
+juju relate data-integrator pgbouncer-external
+juju relate pgbouncer-external db1database
+
+juju run data-integrator/leader get-credentials
+```
\ No newline at end of file
diff --git a/docs/how-to/h-async/h-async-remove-recover.md b/docs/how-to/h-async/h-async-remove-recover.md
new file mode 100644
index 0000000000..d5dc15bcb0
--- /dev/null
+++ b/docs/how-to/h-async/h-async-remove-recover.md
@@ -0,0 +1,66 @@
+# Remove or recover a cluster
+[note type="caution"]
+This is an internal article. **Do not use it in production!**
+
+Contact the [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in this topic.
+[/note]
+
+This guide will cover how to manage clusters using an example PostgreSQL deployment with two servers: one in Rome and one in Lisbon.
+
+## Prerequisites
+* `juju v.3.4.2+`
+* A cross-regional async replication setup
+ * Refer to the page [How to set up clusters](/t/13991)
+
+## Summary
+* [Switchover](#heading--switchover)
+* [Detach a cluster](#heading--detach)
+ * [Reuse a detached cluster](#heading--reuse)
+ * [Remove a detached cluster](#heading--remove)
+* [Recover a cluster](#heading--recover)
+
+
+---
+
+ Switchover
+
+If the primary cluster fails or is removed, it is necessary to appoint a new cluster as primary.
+
+To switchover and promote `lisbon` to primary, one would run the command:
+
+```shell
+juju run -m lisbon db2/leader promote-to-primary
+```
+
+ Detach a cluster
+
+Clusters in an async replica set can be detached. The detached cluster can then be either removed or reused.
+
+Assuming `lisbon` is the current primary, one would run the following command to detach `rome`:
+
+```shell
+juju remove-relation -m lisbon replication-offer db2:replication
+```
+
+The command above will move the `rome` cluster into a detached state (`blocked`) keeping all the data in place.
+
+ Reuse a detached cluster
+
+The following command creates a new cluster in the replica set from the detached `rome` cluster, keeping its existing data in use:
+
+```shell
+juju run -m rome db1/leader promote-to-primary
+```
+ Remove a detached cluster
+
+The following command removes the detached `rome` cluster and **destroys its stored data** with the optional `--destroy-storage` flag:
+
+```shell
+juju remove-application -m rome db1 --destroy-storage
+```
+
+ Recover a cluster
+
+**If the integration between clusters was removed** and one side went into a `blocked` state, integrate both clusters again and call the `promote-cluster` action to restore async replication - similar to the "Reuse a detached cluster" step above.
+
+**If the cluster group lost a member entirely** (e.g. `rome` is suddenly no longer available to the cluster group originally consisting of `rome` and `lisbon`), deploy a new `postgresql` application and [set up async replication](/t/13991). The data will be copied automatically after the `promote-cluster` action is called, and the new cluster will join the cluster group.
\ No newline at end of file
diff --git a/docs/how-to/h-async/h-async-set-up.md b/docs/how-to/h-async/h-async-set-up.md
new file mode 100644
index 0000000000..0b7c2db2a3
--- /dev/null
+++ b/docs/how-to/h-async/h-async-set-up.md
@@ -0,0 +1,82 @@
+# Set up clusters for cross-regional async replication
+
+[note type="caution"]
+This is an internal article. **Do not use it in production!**
+
+Contact the [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in this topic.
+[/note]
+
+Cross-regional (or multi-server) asynchronous replication focuses on disaster recovery by distributing data across different servers.
+
+This guide will show you the basics of initiating a cross-regional async setup using an example PostgreSQL deployment with two servers: one in Rome and one in Lisbon.
+
+## Summary
+* [Deploy](#heading--deploy)
+* [Offer](#heading--offer)
+* [Consume](#heading--consume)
+* [Promote or switchover](#heading--promote-switchover)
+* [Scale](#heading--scale)
+
+
+---
+
+ Deploy
+
+To deploy two clusters in different servers, create two juju models - one for the `rome` cluster, one for the `lisbon` cluster. In the example below, we use the config flag `profile=testing` to limit memory usage.
+
+```shell
+juju add-model rome
+juju add-model lisbon
+
+juju switch rome # active model must correspond to cluster
+juju deploy postgresql db1 --channel=14/edge --config profile=testing --base ubuntu@22.04
+
+juju switch lisbon
+juju deploy postgresql db2 --channel=14/edge --config profile=testing --base ubuntu@22.04
+```
+
+ Offer
+
+[Offer](https://juju.is/docs/juju/offer) asynchronous replication in one of the clusters.
+
+```shell
+juju switch rome
+juju offer db1:replication-offer replication-offer
+```
+
+ Consume
+
+Consume asynchronous replication on planned `Standby` cluster (Lisbon):
+```shell
+juju switch lisbon
+juju consume rome.replication-offer
+juju integrate replication-offer db2:replication
+```
+
+
+
+To define the primary cluster, use the `create-replication` action.
+
+```shell
+juju run -m rome db1/leader create-replication
+```
+
+To switchover and use `lisbon` as the primary instead, run
+
+```shell
+juju run -m lisbon db2/leader promote-to-primary
+```
+
+ Scale a cluster
+
+The two clusters work independently, which means that it’s possible to scale each cluster separately. The `-m` flag defines the target of this action, so it can be performed with any active model.
+
+For example:
+
+```shell
+juju add-unit db1 -n 2 -m rome
+juju add-unit db2 -n 2 -m lisbon
+```
+[note]
+Scaling is possible before and after the asynchronous replication is established/created.
+[/note]
\ No newline at end of file
diff --git a/docs/how-to/h-backups/h-configure-s3-aws.md b/docs/how-to/h-backups/h-configure-s3-aws.md
new file mode 100644
index 0000000000..5cc50899ce
--- /dev/null
+++ b/docs/how-to/h-backups/h-configure-s3-aws.md
@@ -0,0 +1,53 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# Configure S3 for AWS
+A Charmed PostgreSQL backup can be stored on any S3-compatible storage. S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator).
+
+This guide will teach you how to deploy and configure the s3-integrator charm for [AWS S3](https://aws.amazon.com/s3/), send the configurations to the Charmed PostgreSQL application, and update it. (To configure S3 for RadosGW, see [this guide](/t/10313))
+
+## Configure s3-integrator
+First, deploy and run the charm:
+```shell
+juju deploy s3-integrator
+juju run s3-integrator/leader sync-s3-credentials access-key= secret-key=
+```
+Then, use `juju config` to add your configuration parameters. For example:
+```shell
+juju config s3-integrator \
+ endpoint="https://s3.us-west-2.amazonaws.com" \
+ bucket="postgresql-test-bucket-1" \
+ path="/postgresql-test" \
+ region="us-west-2"
+```
+[note]
+There is now an experimental configuration option that sets up a retention time (in days) for backups stored in S3: [`experimental-delete-older-than-days`](https://charmhub.io/s3-integrator/configuration?channel=latest/edge#experimental-delete-older-than-days). More info on [this guide](/t/14249)
+[/note]
+
+[note]
+The amazon S3 endpoint must be specified as `s3..amazonaws.com ` within the first 24 hours of creating the bucket. For older buckets, the endpoint `s3.amazonaws.com` can be used.
+
+See [this post](https://repost.aws/knowledge-center/s3-http-307-response) for more information.
+[/note]
+
+## Integrate with Charmed PostgreSQL
+To pass these configurations to Charmed PostgreSQL, integrate the two applications:
+```shell
+juju integrate s3-integrator postgresql
+```
+You can create, list, and restore backups now:
+```shell
+juju run postgresql/leader list-backups
+juju run postgresql/leader create-backup
+juju run postgresql/leader list-backups
+juju run postgresql/leader restore backup-id=
+```
+You can also update your S3 configuration options after relating using:
+```shell
+juju config s3-integrator =
+```
+
+The s3-integrator charm accepts many [configurations](https://charmhub.io/s3-integrator/configure) - enter whichever are necessary for your S3 storage.
\ No newline at end of file
diff --git a/docs/how-to/h-backups/h-configure-s3-radosgw.md b/docs/how-to/h-backups/h-configure-s3-radosgw.md
new file mode 100644
index 0000000000..d13a40d37b
--- /dev/null
+++ b/docs/how-to/h-backups/h-configure-s3-radosgw.md
@@ -0,0 +1,52 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# Configure S3 for RadosGW
+
+A Charmed PostgreSQL backup can be stored on any S3-compatible storage. S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator).
+
+This guide will teach you how to deploy and configure the s3-integrator charm on Ceph via [RadosGW](https://docs.ceph.com/en/quincy/man/8/radosgw/), send the configuration to a Charmed PostgreSQL application, and update it. (To configure S3 for AWS, see [this guide](/t/9681))
+
+## Configure s3-integrator
+First, install the MinIO client and create a bucket:
+```shell
+mc config host add dest https://radosgw.mycompany.fqdn --api S3v4 --lookup path
+mc mb dest/backups-bucket
+```
+Then, deploy and run the charm:
+```shell
+juju deploy s3-integrator
+juju run s3-integrator/leader sync-s3-credentials access-key= secret-key=
+```
+Lastly, use `juju config` to add your configuration parameters. For example:
+```shell
+juju config s3-integrator \
+ endpoint="https://radosgw.mycompany.fqdn" \
+ bucket="backups-bucket" \
+ path="/postgresql" \
+ region="" \
+ s3-api-version="" \
+ s3-uri-style="path" \
+ tls-ca-chain="$(base64 -w0 /path-to-your-server-ca-file)"
+```
+## Integrate with Charmed PostgreSQL
+To pass these configurations to Charmed PostgreSQL, integrate the two applications:
+```shell
+juju integrate s3-integrator postgresql
+```
+You can create, list, and restore backups now:
+```shell
+juju run postgresql/leader list-backups
+juju run postgresql/leader create-backup
+juju run postgresql/leader list-backups
+juju run postgresql/leader restore backup-id=
+```
+
+You can also update your S3 configuration options after integrating using
+```shell
+juju config s3-integrator =
+```
+The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your S3 storage.
\ No newline at end of file
diff --git a/docs/how-to/h-backups/h-create-backup.md b/docs/how-to/h-backups/h-create-backup.md
new file mode 100644
index 0000000000..8d9325c1cf
--- /dev/null
+++ b/docs/how-to/h-backups/h-create-backup.md
@@ -0,0 +1,58 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# How to create and list backups
+
+This guide contains recommended steps and useful commands for creating and managing backups to ensure smooth restores.
+
+## Prerequisites
+* A cluster with at [least three nodes](/t/charmed-postgresql-how-to-manage-units/9689?channel=14/stable) deployed
+* Access to S3 storage
+* [Configured settings for S3 storage](/t/charmed-postgresql-how-to-configure-s3/9681?channel=14/stable)
+
+## Summary
+- [Save your current cluster credentials](#heading--save-credentials), as you'll need them for restoring
+- [Create a backup](#heading--create-backup)
+- [List backups](#heading--list-backups) to check the availability and status of your backups
+
+---
+
+Save your current cluster credentials
+For security reasons, charm credentials are not stored inside backups. So, if you plan to restore to a backup at any point in the future, **you will need the `operator`, `replication`, and `rewind` user passwords for your existing cluster**.
+
+You can retrieve them with:
+```shell
+juju run postgresql/leader get-password username=operator
+juju run postgresql/leader get-password username=replication
+juju run postgresql/leader get-password username=rewind
+```
+For more context about passwords during a restore, check [How to migrate a cluster > Manage cluster passwords](/t/9691#heading--manage-cluster-passwords).
+
+Create a backup
+Once you have a three-node cluster with configurations set for S3 storage, check that Charmed PostgreSQL is `active` and `idle` with `juju status`.
+
+Once Charmed PostgreSQL is `active` and `idle`, you can create your first backup with the `create-backup` command:
+```shell
+juju run postgresql/leader create-backup
+```
+By default, backups created with command above will be **full** backups: a copy of *all* your data will be stored in S3. There are 2 other supported types of backups (available in revision 416+, currently in channel `14/edge` only):
+* Differential: Only modified files since the last full backup will be stored.
+* Incremental: Only modified files since the last successful backup (of any type) will be stored.
+
+To specify the desired backup type, use the [`type`](https://charmhub.io/postgresql/actions?channel=14/edge#create-backup) parameter:
+```shell
+juju run postgresql/leader create-backup type={full|differential|incremental}
+```
+
+**Tip**: To avoid unnecessary service downtime, always use non-primary units for the action `create-backup`. Keep in mind that:
+* TLS enabled: disables the command from running on *primary units*.
+* TLS **not** enabled: disables the command from running on *non-primary units*.
+
+List backups
+You can list your available, failed, and in progress backups by running the `list-backups` command:
+```shell
+juju run postgresql/leader list-backups
+```
\ No newline at end of file
diff --git a/docs/how-to/h-backups/h-manage-backup-retention.md b/docs/how-to/h-backups/h-manage-backup-retention.md
new file mode 100644
index 0000000000..c41a80c951
--- /dev/null
+++ b/docs/how-to/h-backups/h-manage-backup-retention.md
@@ -0,0 +1,45 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# Manage backup retention
+
+Charmed PostgreSQL backups can be managed via a retention policy. This retention can be set by the user in the form of a configuration parameter in the charm [`s3-integrator`](https://charmhub.io/s3-integrator) via the config option [`experimental-delete-older-than-days`](https://charmhub.io/s3-integrator/configuration?channel=latest/edge#experimental-delete-older-than-days).
+
+This guide will teach you how to set this configuration and how it works in managing existing backups.
+
+[note type="caution"]
+**Note**: This is an **EXPERIMENTAL** parameter, use it with caution.
+[/note]
+
+## Configure S3-integrator charm
+If not done already, deploy and run the charm:
+```shell
+juju deploy s3-integrator
+juju run s3-integrator/leader sync-s3-credentials access-key= secret-key=
+```
+Then, use `juju config` to add the desired retention time in days:
+```shell
+juju config s3-integrator experimental-delete-older-than-days=
+```
+To pass these configurations to a Charmed PostgreSQL application, integrate the two applications:
+```shell
+juju integrate s3-integrator postgresql
+```
+If at any moment it is desired to remove this option, the user can erase this configuration from the charm:
+```shell
+juju config s3-integrator --reset experimental-delete-older-than-days
+```
+[note]
+**Note**: This configuration will be enforced in **every** Charmed PostgreSQL application related to the configured S3-integrator charm
+[/note]
+
+[note]
+**Note**: The retention is **not** enforced automatically once a backup is older than the set amount of days: Backups older than the set retention time will only get expired only once a newer backup is created.
+
+This behavior avoids complete backup deletion if there has been no newer backups created in the charm.
+[/note]
+
+The s3-integrator charm accepts many [configurations](https://charmhub.io/s3-integrator/configure) - enter whichever are necessary for your S3 storage.
\ No newline at end of file
diff --git a/docs/how-to/h-backups/h-migrate-cluster.md b/docs/how-to/h-backups/h-migrate-cluster.md
new file mode 100644
index 0000000000..d8399962ec
--- /dev/null
+++ b/docs/how-to/h-backups/h-migrate-cluster.md
@@ -0,0 +1,49 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# How to migrate a cluster
+
+This is a guide on how to restore a backup that was made from a different cluster, (i.e. cluster migration via restore).
+
+To perform a basic restore (from a *local* backup), see [Charmed PostgreSQL VM | How to restore a local backup](/t/charmed-postgresql-how-to-restore-backup/9693?channel=14/stable).
+
+## Prerequisites
+Restoring a backup from a previous cluster to a current cluster requires:
+- A single unit Charmed PostgreSQL deployed and running
+- Access to S3 storage
+- [Configured settings for S3 storage](/t/charmed-postgresql-how-to-configure-s3/9681?channel=14/stable)
+- Backups from the previous cluster in your S3 storage
+- Passwords from your previous cluster
+
+---
+
+Manage cluster passwords
+When you restore a backup from an old cluster, it will restore the password from the previous cluster to your current cluster. Set the password of your current cluster to the previous cluster’s password:
+```shell
+juju run postgresql/leader set-password username=operator password=
+juju run postgresql/leader set-password username=replication password=
+juju run postgresql/leader set-password username=rewind password=
+```
+## List backups
+To view the available backups to restore, use the command `list-backups`:
+```shell
+juju run postgresql/leader list-backups
+```
+This shows a list of the available backups (it is up to you to identify which `backup-id` corresponds to the previous-cluster):
+```shell
+ backups: |-
+ backup-id | backup-type | backup-status
+ ----------------------------------------------------
+ YYYY-MM-DDTHH:MM:SSZ | physical | finished
+```
+
+## Restore backup
+To restore your current cluster to the state of the previous cluster, run the `restore` command and pass the correct `backup-id` to the command:
+ ```shell
+juju run postgresql/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ
+```
+
+Your restore will then be in progress. Once it is complete, your current cluster will represent the state of the previous cluster.
\ No newline at end of file
diff --git a/docs/how-to/h-backups/h-restore-backup.md b/docs/how-to/h-backups/h-restore-backup.md
new file mode 100644
index 0000000000..b6ba3402d7
--- /dev/null
+++ b/docs/how-to/h-backups/h-restore-backup.md
@@ -0,0 +1,41 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# How to restore a local backup
+
+This is a guide on how to restore a locally made backup.
+
+To restore a backup that was made from a *different* cluster, (i.e. cluster migration via restore), see [How to migrate cluster using backups](/t/charmed-postgresql-how-to-migrate-cluster-via-restore/9691?channel=14/stable):
+
+
+## Prerequisites
+- Deployments have been [scaled-down](/t/charmed-postgresql-how-to-manage-units/9689?channel=14/stable) to a single PostgreSQL unit (scale it up after the backup is restored)
+- Access to S3 storage
+- [Configured settings for S3 storage](/t/charmed-postgresql-how-to-configure-s3/9681?channel=14/stable)
+- [Existing backups in your S3storage](/t/charmed-postgresql-how-to-create-and-list-backups/9683?channel=14/stable)
+
+---
+
+## List backups
+To view the available backups to restore, use the command `list-backups`:
+```shell
+juju run postgresql/leader list-backups
+```
+
+This should show your available backups like in the sample output below:
+```shell
+ backups: |-
+ backup-id | backup-type | backup-status
+ ----------------------------------------------------
+ YYYY-MM-DDTHH:MM:SSZ | physical | finished
+```
+## Restore backup
+To restore a backup from that list, run the `restore` command and pass the corresponding `backup-id`:
+ ```shell
+juju run postgresql/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ
+```
+
+Your restore will then be in progress.
\ No newline at end of file
diff --git a/docs/how-to/h-connect-your-charm/h-connect-migrate-backup-restore.md b/docs/how-to/h-connect-your-charm/h-connect-migrate-backup-restore.md
new file mode 100644
index 0000000000..b3885cc68b
--- /dev/null
+++ b/docs/how-to/h-connect-your-charm/h-connect-migrate-backup-restore.md
@@ -0,0 +1,41 @@
+# Migrate database data using ‘backup/restore’
+
+This is a guide for migrating data from modern charms. To migrate [legacy charms](/t/11013) data, refer to the guide [Migrate data via pg_dump](/t/10690).
+
+This Charmed PostgreSQL operator is able to restore its own[backups](/t/9693) stored on [S3-compatible storage](/t/9681). The same restore approach is applicable to restore [foreign backups](/t/9691) made by different Charmed PostgreSQL installation or even another PostgreSQL charm. The backup have to be created manually using [pgBackRest](https://pgbackrest.org/)!
+
+[note type="caution"]
+**Warning:** The Canonical Data Team describes here the general approach and does NOT support nor guarantee the restoration results.
+
+Always test a migration in a test environment before performing it in production!
+[/note]
+
+## Prerequisites
+* **Check [your application compatibility](/t/10690)** with Charmed PostgreSQL VM before migrating production data from legacy charm
+* Make sure **PostgreSQL versions are identical** before the migration
+
+## Migrate database data
+Below is the *general approach* to the migration (see warning above!):
+
+1. **Retrieve root/admin level credentials from legacy charm.**
+
+ See examples [here](/t/12163).
+
+2. **Install [pgBackRest](https://pgbackrest.org/) inside the old charm OR nearby.**
+
+ Ensure the version is compatible with pgBackRest in the new `Charmed PostgreSQL` revision you are going to deploy! See examples [here](https://pgbackrest.org/user-guide.html#installation).
+
+ **Note**: You can use `charmed-postgresql` [SNAP](https://snapcraft.io/charmed-postgresql)/[ROCK](https://github.com/canonical/charmed-postgresql-rock) directly. More details [here](/t/11857#hld).
+
+3. **Configure storage for database backup (local or remote, S3-based is recommended).**
+
+4. **Create a first full logical backup during the off-peak**
+
+ See an example of backup command [here](https://github.com/canonical/postgresql-k8s-operator/commit/f39caaa4c5c85afdb157bd53df54a24a1b9687ac#diff-cc5993b9da2438ecff27897b3ab9d2f9bc445cbf5b4f6369a1a0c2f404fe6a4fR186-R212).
+
+5. **[Restore the foreign backup](/t/9691) to the Charmed PostgreSQL installation in your test environment.**
+6. **Perform all the necessary tests to make sure your application accepted the new database.**
+7. **Schedule and perform the final production migration, re-using the last steps above.**
+
+---
+Do you have questions? [Contact us](/t/11863) if you are interested in such a data migration!
\ No newline at end of file
diff --git a/docs/how-to/h-connect-your-charm/h-connect-migrate-pgdump.md b/docs/how-to/h-connect-your-charm/h-connect-migrate-pgdump.md
new file mode 100644
index 0000000000..50fa2da48b
--- /dev/null
+++ b/docs/how-to/h-connect-your-charm/h-connect-migrate-pgdump.md
@@ -0,0 +1,140 @@
+# Migrate database data using `pg_dump` / `pg_restore`
+
+This guide describes database **data** migration only. To migrate charms on new juju interfaces, refer to the guide [How to integrate a database with my charm](/t/11865).
+
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, be aware that:
+
+ - `juju run` replaces `juju run-action --wait` in `juju v.2.9`
+ - `juju integrate` replaces `juju relate` and `juju add-relation` in `juju v.2.9`
+
+For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+## Do you need to migrate?
+A database migration is only required if the output of the following command is `latest/stable`:
+
+```shell
+juju show-application postgresql | yq '.[] | .channel'
+```
+Migration is **not** necessary if the output above is `14/stable`!
+
+This guide can be used to copy data between different installations of the same (modern) charm `postgresql`, but the [backup/restore](/t/12164) is more recommended for migrations between modern charms.
+
+## Summary
+The legacy VM charm archived in the `latest/stable` channel, read more [here](/t/10690).
+A minor difference in commands might be necessary for different revisions and/or Juju versions, but the general logic remains:
+
+* Deploy the modern charm nearby
+* Request credentials from legacy charm
+* Remove relation to legacy charm (to stop data changes)
+* Perform legacy DB dump (using the credentials above)
+* Upload the legacy charm dump into the modern charm
+* Add relation to modern charm
+* Validate results and remove legacy charm
+
+[note]
+**Note**: Always test migration in a safe environment before performing it in production!
+[/note]
+
+## Prerequisites
+- **[Your application is compatible](/t/10690) with Charmed PostgreSQL VM**
+- A client machine with access to the deployed legacy charm
+- `juju v.2.9` or later (check [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022) for more information about key differences)
+- Enough storage in the cluster to support backup/restore of the databases.
+
+## Obtain existing database credentials
+
+To obtain credentials for existing databases, execute the following commands for **each** database that will be migrated. Take note of these credentials for future steps.
+
+First, define and tune your application and db (database) names. For example:
+```shell
+CLIENT_APP=< my-application/0 >
+OLD_DB_APP=< legacy-postgresql/leader | postgresql/0 >
+NEW_DB_APP=< new-postgresql/leader | postgresql/0 >
+DB_NAME=< your_db_name_to_migrate >
+```
+Then, obtain the username from the existing legacy database via its relation info:
+```shell
+OLD_DB_USER=$(juju show-unit ${CLIENT_APP} | yq '.[] | .relation-info | select(.[].endpoint == "db") | .[0].application-data.user')
+```
+
+## Deploy new PostgreSQL databases and obtain credentials
+
+Deploy new PostgreSQL database charm:
+
+```shell
+juju deploy postgresql ${NEW_DB_APP} --channel 14/stable
+```
+Obtain `operator` user password of new PostgreSQL database from PostgreSQL charm:
+```shell
+NEW_DB_USER=operator
+NEW_DB_PASS=$(juju run ${NEW_DB_APP} get-password | yq '.password')
+```
+
+## Migrate database
+Use the credentials and information obtained in previous steps to perform the database migration with the following procedure.
+
+[note]
+Make sure no new connections were made and that the database has not been altered!
+[/note]
+
+### Create dump from legacy charm
+Remove the relation between application charm and legacy charm:
+```shell
+juju remove-relation ${CLIENT_APP} ${OLD_DB_APP}
+```
+Connect to the database VM of a legacy charm:
+```shell
+juju ssh ${OLD_DB_APP} bash
+```
+Create a dump via Unix socket using credentials from the relation:
+```shell
+mkdir -p /srv/dump/
+OLD_DB_DUMP="legacy-postgresql-${DB_NAME}.sql"
+pg_dump -Fc -h /var/run/postgresql/ -U ${OLD_DB_USER} -d ${DB_NAME} > "/srv/dump/${OLD_DB_DUMP}"
+```
+Exit the database VM:
+```shell
+exit
+```
+### Upload dump to new charm
+Fetch dump locally and upload it to the new Charmed PostgreSQL charm:
+```shell
+juju scp ${OLD_DB_APP}:/srv/dump/${OLD_DB_DUMP} ./${OLD_DB_DUMP}
+juju scp ./${OLD_DB_DUMP} ${NEW_DB_APP}:.
+```
+ssh into new Charmed PostgreSQL charm and create a new database (using `${NEW_DB_PASS}`):
+```shell
+juju ssh ${NEW_DB_APP} bash
+createdb -h localhost -U ${NEW_DB_USER} --password ${DB_NAME}
+```
+Restore the dump (using `${NEW_DB_PASS}`):
+```shell
+pg_restore -h localhost -U ${NEW_DB_USER} --password -d ${DB_NAME} --no-owner --clean --if-exists ${OLD_DB_DUMP}
+```
+
+## Integrate with modern charm
+Integrate (formerly "relate" in `juju v.2.9`) your application and new PostgreSQL database charm (using the modern `database` endpoint)
+```shell
+juju integrate ${CLIENT_APP} ${NEW_DB_APP}:database
+```
+
+If the `database` endpoint (from the `postgresql_client` interface) is not yet supported, use instead the `db` endpoint from the legacy `pgsql` interface:
+```shell
+juju integrate ${CLIENT_APP} ${NEW_DB_APP}:db
+```
+
+## Verify database migration
+
+Test your application to make sure the data is available and in a good condition.
+
+## Remove old databases
+
+Test your application and if you are happy with a data migration, do not forget to remove legacy charms to keep the house clean:
+
+```shell
+juju remove-application --destroy-storage
+```
\ No newline at end of file
diff --git a/docs/how-to/h-connect-your-charm/h-integrate-with-your-charm.md b/docs/how-to/h-connect-your-charm/h-integrate-with-your-charm.md
new file mode 100644
index 0000000000..36eee72e8c
--- /dev/null
+++ b/docs/how-to/h-connect-your-charm/h-integrate-with-your-charm.md
@@ -0,0 +1,68 @@
+# How to integrate a database with my charm
+
+Charmed PostgreSQL can be integrated with any charmed application that supports its interfaces. This page provides some guidance and resources for charm developers to develop, integrate, and troubleshoot their charm so that it may connect with PostgreSQL.
+
+## Summary
+* Check supported interfaces
+* Integrate your charm with PostgreSQL
+* Troubleshooting & testing
+* FAQ
+
+---
+
+## Check supported interfaces
+First, we recommend that you check [the supported interfaces](/t/10251) of the current charm. You have options to use modern (preferred) or legacy interfaces.
+
+Most existing charms currently use [ops-lib-pgsql](https://github.com/canonical/ops-lib-pgsql) interface (legacy). For new charms, **Canonical recommends using [data-platform-libs](https://github.com/canonical/data-platform-libs) instead.**
+
+Legacy charm details are described [here](/t/10690).
+
+## Integrate your charm with PostgreSQL
+**For an introduction** to the concepts of Juju integrations, see [Juju | Integration](https://juju.is/docs/juju/integration).
+
+**For a detailed tutorial** about integrating your charm with the PostgreSQL charm, refer to [Juju | Integrate your charm with PostgreSQL](https://juju.is/docs/sdk/integrate-your-charm-with-postgresql).
+
+**For some practical examples**, take a look at the following:
+* [postgresql-test-app](https://github.com/canonical/postgresql-test-app) GitHub repository
+* [juju-sdk-tutorial-k8s](https://github.com/canonical/juju-sdk-tutorial-k8s/tree/04_integrate_with_psql) - the branch `04_integrate_with_psql` describes integration with Charmed PostgreSQL K8s
+* [How to migrate Nextcloud to new PostgreSQL (vm-charms)](/t/10969) guide
+
+## Troubleshooting & testing
+* To learn the basics of charm debugging, start with [Juju | How to debug a charm](https://juju.is/docs/sdk/debug-a-charm)
+* To troubleshoot PostgreSQL, check the [Troubleshooting](/t/11864) reference
+* To test PostgreSQL and other charms, check the [Testing](/t/11773) reference
+
+## FAQ
+**Does the requirer need to set anything in relation data?**
+>It depends on the interface. Check the `postgresql_client` [interface requirements](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/postgresql_client/v0/README.md).
+
+**Is there a charm library available, or does my charm need to compile the postgresql relation data on its own?**
+>Yes, the library is available: [data-platform-libs](https://github.com/canonical/data-platform-libs). The integration is trivial: [example](https://github.com/nextcloud-charmers/nextcloud-charms/pull/78).
+
+**How do I obtain the database url/uri?**
+>This feature is [planned](https://warthogs.atlassian.net/browse/DPE-2278) but currently missing.
+>
+>Meanwhile, use [this](https://github.com/nextcloud-charmers/nextcloud-charms/blob/91f9eebb4d40eaaff9c2f7513f66980df75c2a3b/operator-nextcloud/src/charm.py#L610-L631) example or refer to the function below.
+>
+>```python
+>def _db_connection_string(self) -> str:
+> """Report database connection string using info from relation databag."""
+> relation = self.model.get_relation("database")
+> if not relation:
+> return ""
+>
+> data = self._database.fetch_relation_data()[relation.id]
+> username = data.get("username")
+> password = data.get("password")
+> endpoints = data.get("endpoints")
+>
+> return f"postgres://{username}:{password}@{endpoints}/ratings"
+> ```
+
+
+
+## Success stories
+
+* [How to migrate Nextcloud to new PostgreSQL (vm-charms)](/t/10969).
+
+[Contact us](/t/11863) if you have any questions, issues, or ideas!
\ No newline at end of file
diff --git a/docs/how-to/h-enable-plugins-extensions.md b/docs/how-to/h-enable-plugins-extensions.md
new file mode 100644
index 0000000000..261c86e46b
--- /dev/null
+++ b/docs/how-to/h-enable-plugins-extensions.md
@@ -0,0 +1,34 @@
+# How to enable plugins/extensions
+
+## Prerequisites
+* A deployed [Charmed PostgreSQL operator](/t/charmed-postgresql-tutorial-deploy-postgresql/9697?channel=14/edge)
+
+## Enable plugin/extension
+Enable the plugin/extension by setting `True` as the value of its respective config option, like in the following example:
+```shell
+juju config postgresql plugin__enable=True
+```
+## Integrate your application
+Integrate (formerly known as "relate" in `juju v.2.9`) your application charm with the PostgreSQL charm:
+
+```shell
+juju integrate postgresql
+```
+
+If your application charm requests extensions through `db` or `db-admin` relation data, but the extension is not enabled yet, you'll see that the PostgreSQL application goes into a blocked state with the following message:
+```shell
+postgresql/0* blocked idle 10.1.123.30 extensions requested through relation
+```
+In the [Juju debug logs](https://juju.is/docs/juju/juju-debug-log) we can see the list of extensions that need to be enabled:
+
+```shell
+unit-postgresql-0: 18:04:51 ERROR unit.postgresql/0.juju-log db:5: ERROR - `extensions` (pg_trgm, unaccent) cannot be requested through relations - Please enable extensions through `juju config` and add the relation again.
+```
+
+After enabling the needed extensions through the config options, the charm will unblock. If you have removed the relation, you can add it back again.
+
+If the application charm uses the new `postgresql_client` interface, it can use the [is_postgresql_plugin_enabled](https://charmhub.io/data-platform-libs/libraries/data_interfaces#databaserequires-is_postgresql_plugin_enabled) helper method from the data interfaces library to check whether the plugin/extension is already enabled in the database.
+
+[note]
+**Note:** Not all PostgreSQL extensions are available. The list of supported extensions is available at [ Supported plugins/extensions](/t/charmed-postgresql-k8s-reference-supported-plugins-extensions/10946).
+[/note]
\ No newline at end of file
diff --git a/docs/how-to/h-monitor/h-enable-alert-rules.md b/docs/how-to/h-monitor/h-enable-alert-rules.md
new file mode 100644
index 0000000000..7819fccb9c
--- /dev/null
+++ b/docs/how-to/h-monitor/h-enable-alert-rules.md
@@ -0,0 +1,67 @@
+# How to enable COS Alert Rules
+Charmed PostgreSQL VM [ships](https://github.com/canonical/postgresql-operator/tree/main/src/prometheus_alert_rules) a pre-configured and pre-enabled list of [Awesome Alert Rules](https://samber.github.io/awesome-prometheus-alerts/):
+
+![Screenshot from 2024-01-18 20-05-52|690x439](upload://j6WSPQ1BzoFzqIg2jm1mTq79SMo.png)
+
+This guide will show how to set up [Pushover](https://pushover.net/) to receive alert notifications from the COS Alert Manager.
+
+For information about accessing and managing COS Alert Rules, refer to the [COS documentation](https://charmhub.io/cos-lite).
+
+## Prerequisites
+* A deployed [Charmed PostgreSQL VM operator](/t/9697)
+* A deployed [`cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
+* Fully configured [COS Monitoring](/t/10600)
+
+## Enable COS alerts for Pushover
+The following section is an example of the [Pushover](https://pushover.net/) alerts aggregator.
+
+The first step is to create a new account on Pushover (or use an existing one). The goal is to have the 'user key' and 'token' to authorize alerts for the Pushover application. Follow this straightforward [Pushover guide](https://support.pushover.net/i175-how-to-get-a-pushover-api-or-pushover-application-token).
+
+Next, create a new [COS Alert Manager](https://charmhub.io/alertmanager-k8s) config (replace `user_key` and `token` with yours):
+```shell
+cat > myalert.yaml << EOF
+```
+```yaml
+global:
+ resolve_timeout: 5m
+ http_config:
+ follow_redirects: true
+ enable_http2: true
+route:
+ receiver: placeholder
+ group_by:
+ - juju_model_uuid
+ - juju_application
+ - juju_model
+ continue: false
+ group_wait: 30s
+ group_interval: 5m
+ repeat_interval: 1h
+receivers:
+- name: placeholder
+ pushover_configs:
+ - user_key:
+ token:
+ url: http:///cos-grafana/alerting/list
+ title: "{{ range .Alerts }}{{ .Labels.severity }} - {{ if .Labels.juju_unit }}{{ .Labels.juju_unit }}{{ else }}{{ .Labels.juju_application }}{{ end }} in model {{ .Labels.juju_model }}: {{ .Labels.alertname }} {{ end }}"
+ message: "{{ range .Alerts }} Job: {{ .Labels.job }} Instance: {{ .Labels.instance }} {{ end }}"
+templates: []
+EOF
+```
+Upload and apply newly the created alert manager config:
+```
+juju switch :
+juju config alertmanager config_file=@myalert.yaml
+```
+
+At this stage, the COS Alert Manager will start sending alert notifications to Pushover. Users can receive them on all supported [Pushover clients/apps](https://pushover.net/clients).
+
+The image below shows an example of the Pushover web client:
+
+![image|690x439](upload://vqUcKpZ5R4wQLmY2HYGV5fz5pNU.jpeg)
+
+## Alert receivers
+
+The similar way as above, COS alerts can be send to the long [list of supported receivers](https://prometheus.io/docs/alerting/latest/configuration/#receiver-integration-settings).
+
+Do you have questions? [Contact us](/t/11852)!
\ No newline at end of file
diff --git a/docs/how-to/h-monitor/h-enable-monitoring.md b/docs/how-to/h-monitor/h-enable-monitoring.md
new file mode 100644
index 0000000000..83e63b8334
--- /dev/null
+++ b/docs/how-to/h-monitor/h-enable-monitoring.md
@@ -0,0 +1,131 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# How to enable monitoring (COS)
+
+## Prerequisites
+Enable monitoring requires that you:
+* A deployed [Charmed PostgreSQL VM operator](/t/charmed-postgresql-tutorial-deploy-postgresql/9697?channel=14/edge)
+* A deployed [`cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
+
+---
+
+First, switch to the COS K8s environment and offer COS interfaces to be cross-model integrated with the Charmed PostgreSQL VM model.
+
+To switch to the Kubernetes controller for the COS model, run
+```shell
+juju switch :
+```
+To offer the COS interfaces, run
+```shell
+juju offer grafana:grafana-dashboard grafana
+juju offer loki:logging loki
+juju offer prometheus:receive-remote-write prometheus
+```
+## Consume offers via the PostgreSQL model
+Next, we will switch to the Charmed PostgreSQL VM model, find offers, and consume them.
+
+We are currently on the Kubernetes controller for the COS model. To switch to the PostgreSQL model, run
+```shell
+juju switch :
+```
+To find offers, run
+```shell
+juju find-offers :admin/
+```
+The output should be similar to the sample below, where `k8s` is the k8s controller name and `cos` is the model where `cos-lite` has been deployed:
+```shell
+Store URL Access Interfaces
+k8s admin/cos.grafana admin grafana_dashboard:grafana-dashboard
+k8s admin/cos.loki admin loki_push_api:logging
+k8s admin/cos.prometheus admin prometheus-receive-remote-write:receive-remote-write
+...
+```
+
+To consume offers to be reachable in the current model, run
+```shell
+juju consume :admin/cos.prometheus
+juju consume :admin/cos.loki
+juju consume :admin/cos.grafana
+```
+## Deploy and integrate Grafana
+First, deploy the [`grafana-agent`](https://charmhub.io/grafana-agent) subordinate charm.
+```shell
+juju deploy grafana-agent
+```
+Then, integrate (previously known as "relate") it with PostgreSQL
+```shell
+juju integrate postgresql:cos-agent grafana-agent
+```
+ Finally, integrate `grafana-agent` with consumed COS offers:
+```shell
+juju integrate grafana-agent grafana
+juju integrate grafana-agent loki
+juju integrate grafana-agent prometheus
+```
+After this is complete, Grafana will show the new dashboard `PostgreSQL Exporter` and will allow access to Charmed PostgreSQL logs on Loki.
+
+### Sample outputs
+Below is a sample output of `juju status` on the Charmed PostgreSQL VM model:
+```console
+ubuntu@localhost:~$ juju status
+Model Controller Cloud/Region Version SLA Timestamp
+vmmodel local localhost/localhost 2.9.42 unsupported 00:12:18+02:00
+
+SAAS Status Store URL
+grafana active k8s admin/cos.grafana-dashboards
+loki active k8s admin/cos.loki-logging
+prometheus active k8s admin/cos.prometheus-receive-remote-write
+
+App Version Status Scale Charm Channel Rev Exposed Message
+grafana-agent active 1 grafana-agent edge 5 no
+postgresql 14.7 active 1 postgresql 14/edge 296 no Primary
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/3* active idle 4 10.85.186.140 Primary
+ grafana-agent/0* active idle 10.85.186.140
+
+Machine State Address Inst id Series AZ Message
+4 started 10.85.186.140 juju-fcde9e-4 jammy Running
+```
+
+Example of `juju status` on a COS K8s model:
+```console
+ubuntu@localhost:~$ juju status
+Model Controller Cloud/Region Version SLA Timestamp
+cos k8s microk8s/localhost 2.9.42 unsupported 00:15:31+02:00
+
+App Version Status Scale Charm Channel Rev Address Exposed Message
+alertmanager 0.23.0 active 1 alertmanager-k8s stable 47 10.152.183.206 no
+catalogue active 1 catalogue-k8s stable 13 10.152.183.183 no
+grafana 9.2.1 active 1 grafana-k8s stable 64 10.152.183.140 no
+loki 2.4.1 active 1 loki-k8s stable 60 10.152.183.241 no
+prometheus 2.33.5 active 1 prometheus-k8s stable 103 10.152.183.240 no
+traefik 2.9.6 active 1 traefik-k8s stable 110 10.76.203.178 no
+
+Unit Workload Agent Address Ports Message
+alertmanager/0* active idle 10.1.84.125
+catalogue/0* active idle 10.1.84.127
+grafana/0* active idle 10.1.84.83
+loki/0* active idle 10.1.84.79
+prometheus/0* active idle 10.1.84.96
+traefik/0* active idle 10.1.84.119
+
+Offer Application Charm Rev Connected Endpoint Interface Role
+grafana grafana grafana-k8s 64 1/1 grafana-dashboard grafana_dashboard requirer
+loki loki loki-k8s 60 1/1 logging loki_push_api provider
+prometheus prometheus prometheus-k8s 103 1/1 receive-remote-write prometheus_remote_write provider
+```
+
+### Connect Grafana web interface
+To connect to the Grafana web interface, follow the [Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s?_ga=2.201254254.1948444620.1704703837-757109492.1701777558#heading--browse-dashboards) section of the MicroK8s "Getting started" guide.
+```shell
+juju run grafana/leader get-admin-password --model :
+```
+
+### Example of Charmed PostgreSQL on Grafana
+
+![image|690x353](upload://c7LEKHwQJ25t7BkkR5S9hhs9d4Q.png)
\ No newline at end of file
diff --git a/docs/how-to/h-monitor/h-enable-tracing.md b/docs/how-to/h-monitor/h-enable-tracing.md
new file mode 100644
index 0000000000..f74ba594db
--- /dev/null
+++ b/docs/how-to/h-monitor/h-enable-tracing.md
@@ -0,0 +1,141 @@
+[note]
+**Note**: All commands are written for `juju >= v3.1`
+
+If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# Enable tracing
+
+This guide contains the steps to enable tracing with [Grafana Tempo](https://grafana.com/docs/tempo/latest/) for your PostgreSQL application.
+
+To summarize:
+* [Deploy the Tempo charm in a COS K8s environment](#heading--deploy)
+* [Integrate it with the COS charms](#heading--integrate)
+* [Offer interfaces for cross-model integrations](#heading--offer)
+* [View PostgreSQL traces on Grafana](#heading--view)
+
+[note type="caution"]
+**Warning:** This is feature is in development. It is **not recommended** for production environments.
+
+This feature is available for Charmed PostgreSQL revision 421+ only.
+[/note]
+
+## Prerequisites
+Enabling tracing with Tempo requires that you:
+- Have deployed a Charmed PostgreSQL application
+ - See [How to scale units](https://discourse.charmhub.io/t/charmed-postgresql-how-to-scale-units/9689)
+- Have deployed a 'cos-lite' bundle from the `latest/edge` track in a Kubernetes environment
+ - See [Getting started on MicroK8s](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
+
+---
+
+ Deploy Tempo
+
+First, switch to the Kubernetes controller where the COS model is deployed:
+
+```shell
+juju switch :
+```
+Then, deploy the [`tempo-k8s`](https://charmhub.io/tempo-k8s) charm:
+```shell
+juju deploy -n 1 tempo-k8s --channel latest/edge
+```
+
+ Integrate with the COS charms
+
+Integrate `tempo-k8s` with the COS charms as follows:
+
+```shell
+juju integrate tempo-k8s:grafana-dashboard grafana:grafana-dashboard
+juju integrate tempo-k8s:grafana-source grafana:grafana-source
+juju integrate tempo-k8s:ingress traefik:traefik
+juju integrate tempo-k8s:metrics-endpoint prometheus:metrics-endpoint
+juju integrate tempo-k8s:logging loki:logging
+```
+If you would like to instrument traces from the COS charms as well, create the following integrations:
+```shell
+juju integrate tempo-k8s:tracing alertmanager:tracing
+juju integrate tempo-k8s:tracing catalogue:tracing
+juju integrate tempo-k8s:tracing grafana:tracing
+juju integrate tempo-k8s:tracing loki:tracing
+juju integrate tempo-k8s:tracing prometheus:tracing
+juju integrate tempo-k8s:tracing traefik:tracing
+```
+
+ Offer interfaces
+
+Next, offer interfaces for cross-model integrations from the model where Charmed PostgreSQL is deployed.
+
+To offer the Tempo integration, run
+
+```shell
+juju offer tempo-k8s:tracing
+```
+
+Then, switch to the Charmed PostgreSQL model, find the offers, and integrate (relate) with them:
+
+```shell
+juju switch :
+
+juju find-offers :
+```
+> :exclamation: Do not miss the "`:`" in the command above.
+
+Below is a sample output where `k8s` is the K8s controller name and `cos` is the model where `cos-lite` and `tempo-k8s` are deployed:
+
+```shell
+Store URL Access Interfaces
+k8s admin/cos.tempo-k8s admin tracing:tracing
+```
+
+Next, consume this offer so that it is reachable from the current model:
+
+```shell
+juju consume k8s:admin/cos.tempo-k8s
+```
+
+Relate Charmed PostgreSQL with the above consumed interface:
+
+```shell
+juju integrate postgresql:tracing tempo-k8s:tracing
+```
+
+Wait until the model settles. The following is an example of the `juju status --relations` on the Charmed PostgreSQL model:
+
+```shell
+Model Controller Cloud/Region Version SLA Timestamp
+database lxd localhost/localhost 3.4.3 unsupported 19:32:36Z
+
+SAAS Status Store URL
+tempo-k8s active k8s admin/cos.tempo-k8s
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql 14.11 active 1 postgresql 14/candidate 422 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/1* active idle 1 10.205.193.156 5432/tcp Primary
+
+Machine State Address Inst id Base AZ Message
+1 started 10.205.193.156 juju-ceca46-1 ubuntu@22.04 Running
+
+Integration provider Requirer Interface Type Message
+postgresql:database-peers postgresql:database-peers postgresql_peers peer
+postgresql:restart postgresql:restart rolling_op peer
+postgresql:upgrade postgresql:upgrade upgrade peer
+tempo-k8s:tracing postgresql:tracing tracing regular
+
+```
+
+[note]
+**Note:** All traces are exported to Tempo using HTTP. Support for sending traces via HTTPS is an upcoming feature.
+[/note]
+
+ View traces
+
+After this is complete, the Tempo traces will be accessible from Grafana under the `Explore` section with `tempo-k8s` as the data source. You will be able to select `postgresql` as the `Service Name` under the `Search` tab to view traces belonging to Charmed PostgreSQL.
+
+Below is a screenshot demonstrating a Charmed PostgreSQL trace:
+
+![Example PostgreSQL trace with Grafana Tempo|690x382](upload://2ts8eOnNODTJnFrfeGGD20Lj5lR.jpeg)
+
+Feel free to read through the [Tempo documentation](https://discourse.charmhub.io/t/tempo-k8s-docs-index/14005) at your leisure to explore its deployment and its integrations.
\ No newline at end of file
diff --git a/docs/how-to/h-set-up/h-deploy-lxd.md b/docs/how-to/h-set-up/h-deploy-lxd.md
new file mode 100644
index 0000000000..286ca7fc3b
--- /dev/null
+++ b/docs/how-to/h-set-up/h-deploy-lxd.md
@@ -0,0 +1,30 @@
+# How to deploy on LXD
+
+For a detailed walkthrough of deploying the charm on LXD, refer to the [Charmed PostgreSQL Tutorial](/t/9707).
+
+For a short summary of the commands on Ubuntu 22.04 LTS, see below:
+```shell
+sudo snap install multipass
+multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs
+multipass shell my-vm
+
+juju add-model postgresql
+juju deploy postgresql --channel 14/stable
+```
+
+The expected result from `juju status` is something similar to:
+```shell
+Model Controller Cloud/Region Version SLA Timestamp
+postgresql overlord localhost/localhost 2.9.42 unsupported 09:41:53+01:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql active 1 postgresql 14/stable 281 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/0* active idle 0 10.89.49.129
+
+Machine State Address Inst id Series AZ Message
+0 started 10.89.49.129 juju-a8a31d-0 jammy Running
+```
+
+Check the [Testing](/t/11773) reference to test your deployment.
\ No newline at end of file
diff --git a/docs/how-to/h-set-up/h-deploy-maas.md b/docs/how-to/h-set-up/h-deploy-maas.md
new file mode 100644
index 0000000000..be5bd8572e
--- /dev/null
+++ b/docs/how-to/h-set-up/h-deploy-maas.md
@@ -0,0 +1,162 @@
+# How to deploy on MAAS
+
+This guide aims to provide a quick start to deploying Charmed PostgreSQL on MAAS. It summarizes the instructions from the [Build a MAAS and LXD environment with Multipass Tutorial](https://discourse.maas.io/t/5360) to set up and tear down a **playground environment**.
+
+If you want to deploy PostgreSQL on MAAS in a **production environment**, refer to the official [Bootstrap MAAS Tutorial](https://maas.io/docs/tutorial-bootstrapping-maas) followed by the [Charmed PostgreSQL Tutorial](/t/9707).
+
+## Summary
+ * [Bootstrap a Multipass VM](#heading--bootstrap-multipass-vm)
+ * [Configure MAAS](#heading--configure-maas)
+ * [Register MAAS with Juju](#heading--register-maas-juju)
+ * [Deploy Charmed PostgreSQL on MAAS](#heading--deploy-postgresql-maas)
+ * [Test Charmed PostgreSQL deployment](#heading--test-postgresql)
+ * [Clean up the environment](#heading--clean-up)
+
+For further details and explanation about each step, remember you can refer to the [original tutorial](https://discourse.maas.io/t/5360).
+
+---
+ Bootstrap a Multipass VM
+
+Install Multipass and launch a VM:
+```shell
+sudo snap install multipass
+
+wget -qO- https://raw.githubusercontent.com/canonical/maas-multipass/main/maas.yml \
+ | multipass launch --name maas -c8 -m12GB -d50GB --cloud-init -
+```
+> The wget command provides a [cloud-init](https://github.com/canonical/maas-multipass/blob/main/maas.yml) file that will set up the VM's LXD and MAAS environment.
+
+
+
+**1.** Find your MAAS IP with
+```shell
+multipass list
+```
+
+**2.** Open `http://:5240/MAAS/` and log in with the default credentials: username=`admin`, password=`admin`.
+
+**3.** Complete the additional MAAS configuration in the welcome screen.
+
+
+
+4. Wait for image downloads to complete on http://:5240/MAAS/r/images
+
+[![Screenshot from 2024-04-12 12-48-40](upload://kyNPhsHr7GHyFouEpp7sxPytb6g.png)](https://assets.ubuntu.com/v1/901aa34b-image_downloads.png)
+
+
+
+[note]
+Make sure you are downloading 22.04 images as well (20.04 is the current default).
+[/note]
+
+The LXD machine will be up and running after the images downloading and sync is completed.
+
+5. Navigate to http://:5240/MAAS/r/tags
and create a tag with tag-name=juju
. Assign it to the LXD machine.
+
+[![Screenshot from 2024-04-12 12-51-30](upload://44dY32yFYSybmvypdEgDtj0lFid.png)](https://assets.ubuntu.com/v1/1c82f803-tags.png)
+
+
+> **A note on DHCP**
+>
+> MAAS uses DHCP to boot and install new machines. You must enable DHCP manually if you see this banner on MAAS pages:
+![image|690x46](upload://g458TLPPqGIISCFHKdfUwXRepeZ.png)
+>
+> **Make sure to enable DHCP service inside the MAAS VM only.**
+>
+ >Use the internal VM network `fabric-1` on `10.10.10.0/24` and choose a range (e.g. `10.10.10.100-10.10.10.120`). Check the [official MAAS manual](https://maas.io/docs/enabling-dhcp) for more information about enabling DHCP.
+
+
+**6.** Finally, dump MAAS admin user API key to add as Juju credentials later:
+```shell
+sudo maas apikey --username admin
+```
+
+ Register MAAS with Juju
+
+**1.** Enter the Multipass shell and install juju:
+```shell
+multipass shell maas
+sudo snap install juju
+```
+**2.** Add MAAS cloud and credentials into juju.
+
+These commands are interactive, so the following code block shows the commands followed by a sample output. **Make sure to enter your own information when prompted by juju.**
+```shell
+juju add-cloud
+
+> Since Juju 2 is being run for the first time, downloading latest cloud information. Fetching latest public cloud list... Your list of public clouds is up to date, see `juju clouds`. Cloud Types
+> maas
+> manual
+> openstack
+> oracle
+> vsphere
+>
+> Select cloud type: maas
+> Enter a name for your maas cloud: maas-cloud
+> Enter the API endpoint url: http://:5240/MAAS
+> Cloud "maas-cloud"
+```
+```shell
+juju add-credential maas-cloud
+
+> ...
+> Enter credential name: maas-credentials
+>
+> Regions
+> default
+> Select region [any region, credential is not region specific]: default
+> ...
+> Using auth-type "oauth1".
+> Enter maas-oauth: $(paste the MAAS Keys copied from the output above or from http://YOUR_MAAS_IP:5240/MAAS/r/account/prefs/api-keys )
+> Credential "maas-credentials" added locally for cloud "maas-cloud".
+```
+
+**3.** Bootstrap Juju.
+
+Add the flags `--credential` if you registered several MAAS credentials, and `--debug` if you want to see bootstrap details:
+```shell
+juju bootstrap --constraints tags=juju maas-cloud maas-controller
+```
+
+# Deploy Charmed PostgreSQL on MAAS
+```shell
+juju add-model postgresql maas-cloud
+juju deploy postgresql --channel 14/stable
+```
+
+Sample `juju status` output:
+```shell
+Model Controller Cloud/Region Version SLA Timestamp
+postgresql maas-controller maas-cloud/default 3.1.8 unsupported 12:50:26+02:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql 14.10 active 1 postgresql 14/stable 363 no Primary
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/0* active idle 0 10.10.10.5 5432/tcp Primary
+
+Machine State Address Inst id Base AZ Message
+0 started 10.10.10.5 wanted-dassie ubuntu@22.04 default Deployed
+```
+
+# Test your Charmed PostgreSQL deployment
+
+Check the [Testing](/t/11773) reference to test your deployment.
+
+ Clean up the environment
+To stop your VM, run:
+```shell
+multipass stop maas
+```
+If you're done with testing and would like to free up resources on your machine, you can remove the VM entirely.
+
+[note type="caution"]
+**Warning**: When you remove the VM as shown below, **you will lose all the data** in PostgreSQL and any other applications inside it!
+
+For more information, see the docs for [`multipass delete`](https://multipass.run/docs/delete-command).
+[/note]
+
+To completely delete your VM and all its data, run:
+```shell
+multipass delete --purge maas
+```
\ No newline at end of file
diff --git a/docs/how-to/h-set-up/h-enable-tls.md b/docs/how-to/h-set-up/h-enable-tls.md
new file mode 100644
index 0000000000..1b9b31363f
--- /dev/null
+++ b/docs/how-to/h-set-up/h-enable-tls.md
@@ -0,0 +1,80 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.1`
+
+If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# How to enable TLS encryption
+
+This guide will show how to enable TLS using the [`self-signed-certificates` operator](https://github.com/canonical/self-signed-certificates-operator) as an example.
+
+[note type="caution"]
+**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
+
+Check [this guide](/t/11664) for an overview of the signed and self-signed certificate charms available.
+[/note]
+
+## Summary
+* Enable TLS
+* Disable TLS
+* Manage certificates
+ * Check certificates in use
+ * Update keys
+---
+
+## Enable TLS
+
+First, deploy the TLS charm:
+```shell
+juju deploy self-signed-certificates
+```
+
+To enable TLS on `postgresql`, integrate the two applications:
+```shell
+juju integrate self-signed-certificates postgresql
+```
+
+## Disable TLS
+You can disable TLS by removing the integration.
+```shell
+juju remove-relation self-signed-certificates postgresql
+```
+
+## Manage certificates
+### Check certificates in use
+To check the certificates in use by PostgreSQL, you can run:
+```shell
+openssl s_client -starttls postgres -connect : | grep issuer
+```
+
+### Update keys
+Updates to private keys for certificate signing requests (CSR) can be made via the `set-tls-private-key` action. Note that passing keys to external/internal keys should *only be done with* `base64 -w0`, *not* `cat`.
+
+With three replicas, this schema should be followed:
+
+Generate a shared internal key:
+```shell
+openssl genrsa -out internal-key.pem 3072
+```
+Generate external keys for each unit:
+```shell
+openssl genrsa -out external-key-0.pem 3072
+openssl genrsa -out external-key-1.pem 3072
+openssl genrsa -out external-key-2.pem 3072
+```
+
+Apply both private keys to each unit. The shared internal key will be applied only to the juju leader.
+
+```
+juju run postgresql/0 set-tls-private-key "external-key=$(base64 -w0 external-key-0.pem)" "internal-key=$(base64 -w0 internal-key.pem)" --wait
+juju run postgresql/1 set-tls-private-key "external-key=$(base64 -w0 external-key-1.pem)" "internal-key=$(base64 -w0 internal-key.pem)" --wait
+juju run postgresql/2 set-tls-private-key "external-key=$(base64 -w0 external-key-2.pem)" "internal-key=$(base64 -w0 internal-key.pem)" --wait
+```
+
+Updates can also be done with auto-generated keys:
+
+```
+juju run postgresql/0 set-tls-private-key
+juju run postgresql/1 set-tls-private-key
+juju run postgresql/2 set-tls-private-key
+```
\ No newline at end of file
diff --git a/docs/how-to/h-set-up/h-manage-client.md b/docs/how-to/h-set-up/h-manage-client.md
new file mode 100644
index 0000000000..2c4b57ca37
--- /dev/null
+++ b/docs/how-to/h-set-up/h-manage-client.md
@@ -0,0 +1,58 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# How to manage client applications
+
+[Integrations](https://juju.is/docs/juju/relation) (formerly “relations”) are connections between two applications with compatible endpoints. These connections simplify the creation and management of users, passwords, and other shared data.
+
+## Create an integration
+
+**Integrations with new applications are supported via the [postgresql_client](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/postgresql_client/v0/README.md) interface.**
+
+To create an integration, run
+```shell
+juju integrate postgresql
+```
+
+To remove an integration to an application:
+
+```shell
+juju remove-relation postgresql
+```
+
+### Legacy `pgsql` interface
+We have also added support for the database legacy relation from the [original version](https://launchpad.net/postgresql-charm) of the charm via the `pgsql` interface. Note that **this interface is deprecated**.
+
+ ```shell
+juju integrate postgresql:db
+```
+
+Extended permissions can be requested using the `db-admin` endpoint:
+```shell
+juju integrate postgresql:db-admin
+```
+
+
+## Rotate application passwords
+To rotate the passwords of users created for integrated applications, the integration should be removed and integrated again. This process will generate a new user and password for the application.
+
+```shell
+juju remove-relation postgresql
+juju integrate postgresql
+```
+
+### Internal operator user
+The operator user is used internally by the Charmed PostgreSQL VM Operator. The `set-password` action can be used to rotate its password.
+
+To set a specific password for the operator user, run
+```shell
+juju run postgresql/leader set-password password=
+```
+
+To randomly generate a password for the `operator` user, run
+```shell
+juju run postgresql/leader set-password
+```
\ No newline at end of file
diff --git a/docs/how-to/h-set-up/h-scale.md b/docs/how-to/h-set-up/h-scale.md
new file mode 100644
index 0000000000..ad64cfe14b
--- /dev/null
+++ b/docs/how-to/h-set-up/h-scale.md
@@ -0,0 +1,52 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# How to scale units
+
+Replication in PostgreSQL is the process of creating copies of the stored data. This provides redundancy, which means the application can provide self-healing capabilities in case one replica fails. In this context, each replica is equivalent one juju unit.
+
+This guide will show you how to establish and change the amount of juju units used to replicate your data.
+
+## Deploy PostgreSQL with replicas
+
+To deploy PostgreSQL with multiple replicas, specify the number of desired units with the `-n` option.
+```shell
+juju deploy postgresql --channel 14/stable -n
+```
+
+To retrieve the primary replica, one can use the action `get-primary` on any of the units running ` postgresql`:
+```shell
+juju run postgresql/leader get-primary
+```
+
+Similarly, the primary replica is displayed as a status message in `juju status`. However, one should note that this hook gets called on regular time intervals and the primary may be outdated if the status hook has not been called recently.
+
+### `update-status` hook
+
+**We highly suggest configuring the status hook to run frequently.** In addition to reporting the primary, secondaries, and other statuses, the status hook performs self-healing in the case of a network cut.
+
+To change the frequency of the `update-status` hook, run
+```shell
+juju model-config update-status-hook-interval=
+```
+Note that this hook executes a read query to PostgreSQL. On a production level server, this should be configured to occur at a frequency that doesn't overload the server with read requests. Similarly, the hook should not be configured at too quick of a frequency, as this can delay other hooks from running.
+
+You can read more about status hooks [here](https://juju.is/docs/sdk/update-status-event).
+
+## Scale replicas on an existing application
+
+To scale up the cluster, use `juju add-unit`:
+```shell
+juju add-unit postgresql --num-units
+```
+
+To scale down the cluster, use `juju remove-unit`:
+```shell
+juju remove-unit postgresql/
+```
+[note type=negative]
+**Warning**: Do not remove the last unit, it will destroy your data!
+[/note]
\ No newline at end of file
diff --git a/docs/how-to/h-upgrade/h-rollback-major.md b/docs/how-to/h-upgrade/h-rollback-major.md
new file mode 100644
index 0000000000..171cde56e7
--- /dev/null
+++ b/docs/how-to/h-upgrade/h-rollback-major.md
@@ -0,0 +1,9 @@
+# Perform a major rollback
+
+**Example**: PostgreSQL 15 -> PostgreSQL 14
+
+[note type="negative"]
+Currently, this charm only supports PostgreSQL 14. Therefore, only [minor rollbacks](/t/12090) are possible.
+
+Canonical is **NOT** planning to support in-place rollbacks for the major PostgreSQL version change as the old PostgreSQL cluster installation will stay nearby and can be reused for the rollback.
+[/note]
\ No newline at end of file
diff --git a/docs/how-to/h-upgrade/h-rollback-minor.md b/docs/how-to/h-upgrade/h-rollback-minor.md
new file mode 100644
index 0000000000..f64a9cdfe5
--- /dev/null
+++ b/docs/how-to/h-upgrade/h-rollback-minor.md
@@ -0,0 +1,60 @@
+# Minor Rollback
+
+**Example**: PostgreSQL 14.9 -> PostgreSQL 14.8
+(including simple charm revision bump: from revision 43 to revision 42)
+
+[note type="caution"]
+**Warning:** Do NOT trigger `rollback` during the running `upgrade` action! It may cause an unpredictable PostgreSQL cluster state!
+[/note]
+
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, be aware that:
+
+ - `juju run` replaces `juju run-action --wait` in `juju v.2.9`
+ - `juju integrate` replaces `juju relate` and `juju add-relation` in `juju v.2.9`
+
+For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+## Manual rollback
+After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the upgrade process, the process will be halted and enter a failure state.
+
+Even if the underlying PostgreSQL cluster continues to work, it’s important to roll back the charm to
+a previous revision so that an update can be attempted after further inspection of the failure.
+
+## Minor rollback steps
+1. **Prepare** the Charmed PostgreSQL VM application for the in-place rollback.
+2. **Rollback**. Once started, all units in a cluster will be executed sequentially. The rollback will be aborted (paused) if the unit rollback has failed.
+3. **Check**. Make sure the charm and cluster are in a healthy state again.
+
+To execute a rollback, we use a similar procedure to the upgrade. The difference is the charm revision to upgrade to. In this guide's example, we will refresh the charm back to revision `182`.
+
+## Step 1: Prepare
+
+It is necessary to re-run `pre-upgrade-check` action on the leader unit, to enter the upgrade recovery state:
+```shell
+juju run postgresql/leader pre-upgrade-check
+```
+
+## Step 2: Rollback
+When using a charm from charmhub:
+
+```shell
+juju refresh postgresql --revision=182
+```
+
+When deploying from a local charm file, one must have the previous revision charm file and run:
+
+```
+juju refresh postgresql --path=./postgresql_ubuntu-22.04-amd64.charm
+```
+
+Where `postgresql_ubuntu-22.04-amd64.charm` is the previous revision charm file.
+
+The first unit will be rolled out and should rejoin the cluster after settling down. After the refresh command, the juju controller revision for the application will be back in sync with the running Charmed PostgreSQL revision.
+
+## Step 3: Check
+
+Future [improvements are planned](https://warthogs.atlassian.net/browse/DPE-2621) to check the state on pods/clusters on a low level. At the moment check `juju status` to make sure the cluster [state](/t/10844) is OK.
\ No newline at end of file
diff --git a/docs/how-to/h-upgrade/h-upgrade-intro.md b/docs/how-to/h-upgrade/h-upgrade-intro.md
new file mode 100644
index 0000000000..8e1e569828
--- /dev/null
+++ b/docs/how-to/h-upgrade/h-upgrade-intro.md
@@ -0,0 +1,17 @@
+# Charmed PostgreSQL Upgrade
+
+Please choose the appropriate upgrade/rollback tutorial.
+
+Migration:
+
+* [Major upgrade](/t/12087), e.g. PostgreSQL 14 -> PostgreSQL 15.
+
+* [Major rollback](/t/12088), e.g. PostgreSQL 15 -> PostgreSQL 14.
+
+In-place minor upgrade:
+
+* [Minor upgrade](/t/12089), e.g. PostgreSQL 14.8 -> PostgreSQL 14.9
+(including charm revision bump 42 -> 43).
+
+* [Minor rollback](/t/12090), e.g. PostgreSQL 14.9 -> PostgreSQL 14.8
+(including charm revision return 43 -> 42).
\ No newline at end of file
diff --git a/docs/how-to/h-upgrade/h-upgrade-major.md b/docs/how-to/h-upgrade/h-upgrade-major.md
new file mode 100644
index 0000000000..78e845bbde
--- /dev/null
+++ b/docs/how-to/h-upgrade/h-upgrade-major.md
@@ -0,0 +1,9 @@
+# Perform a major upgrade
+
+**Example**: PostgreSQL 14 -> PostgreSQL 15
+
+[note type="negative"]
+Currently, this charm only supports PostgreSQL 14. Therefore, only [minor upgrades](/t/12089) are possible.
+
+Canonical is **NOT** planning to support in-place upgrades for the major version change. The new PostgreSQL cluster will have to be installed nearby, and the data will be copied from the old to the new installation. After announcing the next PostgreSQL major version support, the appropriate manual will be published here.
+[/note]
\ No newline at end of file
diff --git a/docs/how-to/h-upgrade/h-upgrade-minor.md b/docs/how-to/h-upgrade/h-upgrade-minor.md
new file mode 100644
index 0000000000..cb5130077d
--- /dev/null
+++ b/docs/how-to/h-upgrade/h-upgrade-minor.md
@@ -0,0 +1,187 @@
+# Perform a minor upgrade
+
+**Example**: PostgreSQL 14.8 -> PostgreSQL 14.9
+(including simple charm revision bump: from revision 193 to revision 196).
+
+[note]
+This guide is part of [Charmed PostgreSQL Upgrades](/t/12086). Please refer to this page for more information and an overview of the content.
+[/note]
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+## Before upgrading
+Before performing a minor PostgreSQL upgrade, there are some important considerations to take into account:
+* Concurrency with other operations during the upgrade
+* Backing up your data
+* Service disruption
+
+### Concurrency with other operations
+**We strongly recommend to NOT perform any other extraordinary operations on Charmed PostgreSQL cluster while upgrading.**
+
+Some examples are operations like (but not limited to) the following:
+
+* Adding or removing units
+* Creating or destroying new relations
+* Changes in workload configuration
+* Upgrading other connected/related/integrated applications simultaneously
+
+Concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
+### Backups
+**Make sure to have a backup of your data when running any type of upgrade.**
+
+Guides on how to configure backups with S3-compatible storage can be found [here](/t/9683).
+
+### Service disruption
+**It is recommended to deploy your application in conjunction with the [Charmed PgBouncer](https://charmhub.io/pgbouncer) operator.**
+
+This will ensure minimal service disruption, if any.
+
+## Minor upgrade steps
+Here is a summary of the steps to perform a minor upgrade.:
+
+1. **Collect** all necessary pre-upgrade information. It will be necessary for a rollback, if needed. Do NOT skip this step, it is better to be safe than sorry!
+2. **Prepare** your Charmed PostgreSQL Juju application for the in-place upgrade. See the step description below for all technical details executed by charm here.
+3. **Upgrade**. Once started, all units in a cluster will be executed sequentially. The upgrade will be aborted (paused) if the unit upgrade has failed.
+4. (optional) Consider a [**rollback**](/t/12090) in case of disaster. Please inform and include us in your case scenario troubleshooting to trace the source of the issue and prevent it in the future. [Contact us](/t/11863)!
+5. Do a post-upgrade **check**. Make sure all units are in the proper state and the cluster is healthy.
+
+## Step 1: Collect
+
+[note]
+This step is only valid when deploying from [charmhub](https://charmhub.io/).
+
+If a [local charm](https://juju.is/docs/sdk/deploy-a-charm) is deployed (revision is small, e.g. 0-10), make sure the proper/current local revision of the `.charm` file is available BEFORE going further. You might need it for a rollback.
+[/note]
+
+The first step is to record the revision of the running application as a safety measure for a rollback action. To accomplish this, simply run the `juju status` command and look for the deployed Charmed PostgreSQL revision in the command output, e.g.:
+
+```shell
+Model Controller Cloud/Region Version SLA Timestamp
+welcome-lxd lxd localhost/localhost 3.1.6 unsupported 11:35:36+02:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql 14.9 active 3 postgresql 14/candidate 330 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/3* active idle 3 10.3.217.74 5432/tcp
+postgresql/4 active idle 4 10.3.217.95 5432/tcp
+postgresql/5 active idle 5 10.3.217.108 5432/tcp
+
+Machine State Address Inst id Base AZ Message
+3 started 10.3.217.74 juju-d483b7-3 ubuntu@22.04 Running
+4 started 10.3.217.95 juju-d483b7-4 ubuntu@22.04 Running
+5 started 10.3.217.108 juju-d483b7-5 ubuntu@22.04 Running
+```
+
+In this example, the current revision is `330`. Store it safely to use in case of a rollback!
+
+## Step 2: Prepare
+
+Before running the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command, it’s necessary to run the `pre-upgrade-check` action against the leader unit:
+
+```shell
+juju run postgresql/leader pre-upgrade-check
+```
+Make sure there are no errors in the result output.
+
+This action will configure the charm to minimize the amount of primary switchover, among other preparations for a safe upgrade process. After successful execution, the charm is ready to be upgraded.
+
+## Step 3: Upgrade
+
+Use the `juju refresh` command to trigger the charm upgrade process.
+
+Example with channel selection:
+```shell
+juju refresh postgresql --channel 14/edge
+```
+Example with specific revision selection:
+```shell
+juju refresh postgresql --revision=342
+```
+Example with a local charm file:
+```shell
+juju refresh postgresql --path ./postgresql_ubuntu-22.04-amd64.charm
+```
+
+All units will be refreshed (i.e. receive new charm content), and the upgrade will execute one unit at a time.
+
+[note]
+**Note:** To reduce connection disruptions, the order in which the units are upgraded is based on roles:
+
+First the `replica` units, then the `sync-standby` units, and lastly, the `leader`(or `primary`) unit.
+[/note]
+
+ `juju status` will look like:
+
+```shell
+Model Controller Cloud/Region Version SLA Timestamp
+welcome-lxd lxd localhost/localhost 3.1.6 unsupported 11:36:18+02:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql 14.9 active 3 postgresql 14/edge 331 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/3* waiting idle 3 10.3.217.74 5432/tcp other units upgrading first...
+postgresql/4 waiting idle 4 10.3.217.95 5432/tcp other units upgrading first...
+postgresql/5 waiting executing 5 10.3.217.108 5432/tcp waiting for database initialisation
+
+Machine State Address Inst id Base AZ Message
+3 started 10.3.217.74 juju-d483b7-3 ubuntu@22.04 Running
+4 started 10.3.217.95 juju-d483b7-4 ubuntu@22.04 Running
+5 started 10.3.217.108 juju-d483b7-5 ubuntu@22.04 Running
+```
+
+After each unit completes the upgrade, the message will go blank, and a next unit will follow:
+
+```shell
+Model Controller Cloud/Region Version SLA Timestamp
+welcome-lxd lxd localhost/localhost 3.1.6 unsupported 11:36:31+02:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql 14.9 active 3 postgresql 14/edge 331 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/3* waiting idle 3 10.3.217.74 5432/tcp other units upgrading first...
+postgresql/4 maintenance executing 4 10.3.217.95 5432/tcp refreshing the snap
+postgresql/5 active idle 5 10.3.217.108 5432/tcp
+
+Machine State Address Inst id Base AZ Message
+3 started 10.3.217.74 juju-d483b7-3 ubuntu@22.04 Running
+4 started 10.3.217.95 juju-d483b7-4 ubuntu@22.04 Running
+5 started 10.3.217.108 juju-d483b7-5 ubuntu@22.04 Running
+```
+### Important Notes
+**Do NOT trigger `rollback` procedure during the running `upgrade` procedure.**
+It is expected to have some status changes during the process: `waiting`, `maintenance`, `active`.
+
+Make sure `upgrade` has failed/stopped and cannot be fixed/continued before triggering `rollback`!
+
+**Please be patient during huge installations.**
+Each unit should recover shortly after the upgrade, but time can vary depending on the amount of data written to the cluster while the unit was not part of it.
+
+**Incompatible charm revisions or dependencies will halt the process.**
+After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the upgrade process, the upgrade process will be halted and enter a failure state.
+
+## Step 4: Rollback (optional)
+
+The step must be skipped if the upgrade went well!
+
+Although the underlying PostgreSQL Cluster continues to work, it’s important to roll back the charm to a previous revision so that an update can be attempted after further inspection of the failure. Please switch to the dedicated [minor rollback](/t/12090) tutorial if necessary.
+
+## Step 5: Check
+
+Future [improvements are planned](https://warthogs.atlassian.net/browse/DPE-2621) to check the state of a pod/cluster on a low level.
+
+For now, use `juju status` to make sure the cluster [state](/t/10844) is OK.
+
+
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000000..2b6cca235c
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,108 @@
+# Charmed PostgreSQL Documentation
+
+Charmed PostgreSQL is an open-source software operator designed to deploy and operate object-relational databases on IAAS/VM. It packages the powerful database management system [PostgreSQL](https://www.postgresql.org/) into a charmed operator for deployment with [Juju](https://juju.is/docs/juju).
+
+This charm offers automated operations management from day 0 to day 2. It is equipped with several features to securely store and scale complicated data workloads, including TLS encryption, backups, monitoring, password rotation, and easy integration with client applications.
+
+Charmed PostgreSQL meets the need of deploying PostgreSQL in a structured and consistent manner while providing flexibility in configuration. It simplifies deployment, scaling, configuration and management of relational databases in large-scale production environments reliably.
+
+This charmed operator is made for anyone looking for a comprehensive database management interface, whether for operating a complex production environment or simply as a playground to learn more about databases and charms.
+
+[note type="positive"]
+This operator is built for **IAAS/VM**.
+
+For deployments in **Kubernetes** environments, see [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s).
+[/note]
+
+
+
+## In this documentation
+
+| | |
+|--|--|
+| [**Tutorials**](/t/9707) [Get started](/t/9707) - a hands-on introduction to using Charmed PostgreSQL operator for new users | [**How-to guides**](/t/9689) Step-by-step guides covering key operations such as [scaling](/t/9689), [encryption](/t/9685), and [restoring backups](/t/9693) |
+| [**Reference**](/t/13976) Technical information such as [requirements](/t/11743), [release notes](/t/11875), and [plugins](/t/10946) | [**Explanation**](/t/10251) Concepts - discussion and clarification of key topics such as [architecture](/t/11857), [users](/t/10798), and [legacy charms](/t/10690)|
+## Project and community
+
+Charmed PostgreSQL is an official distribution of PostgreSQL. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
+- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
+- [Join the Discourse forum](https://discourse.charmhub.io/tag/postgresql)
+- [Contribute](https://github.com/canonical/postgresql-operator/blob/main/CONTRIBUTING.md) to the code or report an [issue](https://github.com/canonical/postgresql-operator/issues/new/choose)
+- Explore [Canonical Data Fabric solutions](https://canonical.com/data)
+- [Contacts us](/t/11863) for all further questions
+
+## Licencing & Trademark
+The Charmed PostgreSQL Operator is distributed under the [Apache Software Licence version 2.0](https://github.com/canonical/postgresql-operator/blob/main/LICENSE). It depends on [PostgreSQL](https://www.postgresql.org/ftp/source/), which is licensed under the [PostgreSQL License](https://www.postgresql.org/about/licence/) - a liberal open-source licence similar to the BSD or MIT licences.
+
+PostgreSQL is a trademark or registered trademark of PostgreSQL Global Development Group. Other trademarks are the property of their respective owners.
+
+# Contents
+
+1. [Tutorial](tutorial)
+ 1. [Overview](tutorial/t-overview.md)
+ 1. [1. Set up the environment](tutorial/t-set-up.md)
+ 1. [2. Deploy PostgreSQL](tutorial/t-deploy.md)
+ 1. [3. Scale replicas](tutorial/t-scale.md)
+ 1. [4. Manage passwords](tutorial/t-passwords.md)
+ 1. [5. Integrate with other applications](tutorial/t-integrate.md)
+ 1. [6. Enable TLS](tutorial/t-enable-tls.md)
+ 1. [7. Clean up environment](tutorial/t-clean-up.md)
+1. [How-to guides](how-to)
+ 1. [Set up](how-to/h-set-up)
+ 1. [Deploy on LXD](how-to/h-set-up/h-deploy-lxd.md)
+ 1. [Deploy on MAAS](how-to/h-set-up/h-deploy-maas.md)
+ 1. [Scale units](how-to/h-set-up/h-scale.md)
+ 1. [Enable TLS](how-to/h-set-up/h-enable-tls.md)
+ 1. [Manage client applications](how-to/h-set-up/h-manage-client.md)
+ 1. [Back up and restore](how-to/h-backups)
+ 1. [Configure S3 AWS](how-to/h-backups/h-configure-s3-aws.md)
+ 1. [Configure S3 RadosGW](how-to/h-backups/h-configure-s3-radosgw.md)
+ 1. [Create a backup](how-to/h-backups/h-create-backup.md)
+ 1. [Restore a backup](how-to/h-backups/h-restore-backup.md)
+ 1. [Manage backup retention](how-to/h-backups/h-manage-backup-retention.md)
+ 1. [Migrate a cluster](how-to/h-backups/h-migrate-cluster.md)
+ 1. [Monitor (COS)](how-to/h-monitor)
+ 1. [Enable Monitoring](how-to/h-monitor/h-enable-monitoring.md)
+ 1. [Enable Alert Rules](how-to/h-monitor/h-enable-alert-rules.md)
+ 1. [Enable Tracing](how-to/h-monitor/h-enable-tracing.md)
+ 1. [Upgrade](how-to/h-upgrade)
+ 1. [Overview](how-to/h-upgrade/h-upgrade-intro.md)
+ 1. [Perform a major upgrade](how-to/h-upgrade/h-upgrade-major.md)
+ 1. [Perform a major rollback](how-to/h-upgrade/h-rollback-major.md)
+ 1. [Perform a minor upgrade](how-to/h-upgrade/h-upgrade-minor.md)
+ 1. [Perform a minor rollback](how-to/h-upgrade/h-rollback-minor.md)
+ 1. [Connect your charm](how-to/h-connect-your-charm)
+ 1. [Integrate a database with your charm](how-to/h-connect-your-charm/h-integrate-with-your-charm.md)
+ 1. [Migrate data via pg_dump](how-to/h-connect-your-charm/h-connect-migrate-pgdump.md)
+ 1. [Migrate data via backup/restore](how-to/h-connect-your-charm/h-connect-migrate-backup-restore.md)
+ 1. [Cross-regional async replication](how-to/h-async)
+ 1. [Set up clusters](how-to/h-async/h-async-set-up.md)
+ 1. [Integrate with a client app](how-to/h-async/h-async-integrate.md)
+ 1. [Remove or recover a cluster](how-to/h-async/h-async-remove-recover.md)
+ 1. [Enable plugins/extensions](how-to/h-enable-plugins-extensions.md)
+1. [Reference](reference)
+ 1. [Overview](reference/r-overview.md)
+ 1. [Release Notes](reference/r-releases-group)
+ 1. [All releases](reference/r-releases-group/r-releases.md)
+ 1. [Revision 429/430](reference/r-releases-group/r-revision-429.md)
+ 1. [Revision 363](reference/r-releases-group/r-revision-363.md)
+ 1. [Revision 351](reference/r-releases-group/r-revision-351.md)
+ 1. [Revision 336](reference/r-releases-group/r-revision-336.md)
+ 1. [Revision 288](reference/r-releases-group/r-revision-288.md)
+ 1. [System requirements](reference/r-system-requirements.md)
+ 1. [Software testing](reference/r-software-testing.md)
+ 1. [Performance and resource allocation](reference/r-performance.md)
+ 1. [Troubleshooting](reference/h-troubleshooting.md)
+ 1. [Plugins/extensions](reference/r-plugins-extensions.md)
+ 1. [Contacts](reference/r-contacts.md)
+1. [Explanation](explanation)
+ 1. [Architecture](explanation/e-architecture.md)
+ 1. [Interfaces and endpoints](explanation/e-interfaces-endpoints.md)
+ 1. [Statuses](explanation/e-statuses.md)
+ 1. [Users](explanation/e-users.md)
+ 1. [Logs](explanation/e-logs.md)
+ 1. [Juju](explanation/e-juju-details.md)
+ 1. [Legacy charm](explanation/e-legacy-charm.md)
+1. [Search](https://canonical.com/data/docs/postgresql/iaas)
\ No newline at end of file
diff --git a/docs/reference/h-troubleshooting.md b/docs/reference/h-troubleshooting.md
new file mode 100644
index 0000000000..725399ec0c
--- /dev/null
+++ b/docs/reference/h-troubleshooting.md
@@ -0,0 +1,187 @@
+# Troubleshooting
+
+[note type="caution"]
+**Warning:** At the moment, there is **no** ability to [pause an operator](https://warthogs.atlassian.net/browse/DPE-2545).
+
+Make sure your activity will not interfere with the operator itself!
+[/note]
+
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, be aware that:
+
+ - `juju run` replaces `juju run-action --wait` in `juju v.2.9`
+ - `juju integrate` replaces `juju relate` and `juju add-relation` in `juju v.2.9`
+
+For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+## Summary
+This page goes over some recommended tools and approaches to troubleshooting the charm.
+
+Before anything, always run `juju status` to check the [list of charm statuses](/t/10844) and the recommended fixes. This alone may already solve your issue.
+
+Otherwise, this reference goes over how to troubleshoot this charm via:
+- [`juju` logs](#heading--logs)
+- [`snap-based charm`](#heading--snap-based-charm)
+- [Installing extra software](#heading--install-extra-software)
+
+`juju` logs
+
+Please be familiar with [Juju logs concepts](https://juju.is/docs/juju/log) and learn [how to manage Juju logs](https://juju.is/docs/juju/manage-logs).
+
+Always check the Juju logs before troubleshooting further:
+```shell
+juju debug-log --replay --tail
+```
+
+Focus on `ERRORS` (normally there should be none):
+```shell
+juju debug-log --replay | grep -c ERROR
+```
+
+Consider enabling the `DEBUG` log level if you are troubleshooting unusual charm behaviour:
+```shell
+juju model-config 'logging-config==INFO;unit=DEBUG'
+```
+
+The Patroni/PostgreSQL logs are located inside SNAP:
+```shell
+> ls -la /var/snap/charmed-postgresql/common/var/log/*
+
+/var/snap/charmed-postgresql/common/var/log/patroni:
+-rw-r--r-- 1 snap_daemon snap_daemon 292519 Sep 15 21:47 patroni.log
+
+/var/snap/charmed-postgresql/common/var/log/pgbackrest:
+-rw-r----- 1 snap_daemon snap_daemon 7337 Sep 15 21:46 all-server.log
+-rw-r----- 1 snap_daemon snap_daemon 5858 Sep 15 10:41 testbet.postgresql-stanza-create.log
+
+/var/snap/charmed-postgresql/common/var/log/pgbouncer:
+# The pgBouncer should be stopped on Charmed PostgreSQL deployments and produce no logs.
+```
+
+`snap`-based charm
+
+First, check the [operator architecture](/t/11857) to become familiar with snap content, operator building blocks, and running Juju units.
+
+To enter the unit, use:
+```shell
+juju ssh postgresql/0 bash
+```
+
+Make sure the `charmed-postgresql` snap is installed and functional:
+```shell
+ubuntu@juju-fd7874-0:~$ sudo snap list charmed-postgresql
+Name Version Rev Tracking Publisher Notes
+charmed-postgresql 14.9 70 latest/stable dataplatformbot held
+```
+
+From here you can make sure all snap (systemd) services are running:
+```shell
+ubuntu@juju-fd7874-0# sudo snap services
+Service Startup Current Notes
+charmed-postgresql.patroni enabled active -
+charmed-postgresql.pgbackrest-service enabled active -
+charmed-postgresql.prometheus-postgres-exporter enabled active -
+
+ubuntu@juju-fd7874-0:~$ systemctl --failed
+...
+0 loaded units listed.
+
+ubuntu@juju-fd7874-0:~$ ps auxww
+USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
+root 1 0.4 0.0 167364 12716 ? Ss 21:40 0:02 /sbin/init
+root 59 0.0 0.0 64596 20828 ? Ss 21:40 0:00 /lib/systemd/systemd-journald
+root 112 0.0 0.0 11088 5740 ? Ss 21:40 0:00 /lib/systemd/systemd-udevd
+root 115 0.3 0.0 4832 1816 ? Ss 21:40 0:01 snapfuse /var/lib/snapd/snaps/core22_864.snap /snap/core22/864 -o ro,nodev,allow_other,suid
+root 116 0.2 0.0 4896 1880 ? Ss 21:40 0:01 snapfuse /var/lib/snapd/snaps/charmed-postgresql_70.snap /snap/charmed-postgresql/70 -o ro,nodev,allow_other,suid
+root 117 0.0 0.0 4748 1644 ? Ss 21:40 0:00 snapfuse /var/lib/snapd/snaps/core20_2015.snap /snap/core20/2015 -o ro,nodev,allow_other,suid
+root 119 0.0 0.0 4692 1600 ? Ss 21:40 0:00 snapfuse /var/lib/snapd/snaps/lxd_24322.snap /snap/lxd/24322 -o ro,nodev,allow_other,suid
+root 120 0.6 0.0 4768 1840 ? Ss 21:40 0:04 snapfuse /var/lib/snapd/snaps/snapd_19993.snap /snap/snapd/19993 -o ro,nodev,allow_other,suid
+systemd+ 225 0.0 0.0 16116 8100 ? Ss 21:40 0:00 /lib/systemd/systemd-networkd
+systemd+ 227 0.0 0.0 25528 12664 ? Ss 21:40 0:00 /lib/systemd/systemd-resolved
+root 241 0.0 0.0 7284 2792 ? Ss 21:40 0:00 /usr/sbin/cron -f -P
+message+ 243 0.0 0.0 8668 4916 ? Ss 21:40 0:00 @dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only
+root 247 0.0 0.0 33084 18792 ? Ss 21:40 0:00 /usr/bin/python3 /usr/bin/networkd-dispatcher --run-startup-triggers
+syslog 248 0.0 0.0 152764 4748 ? Ssl 21:40 0:00 /usr/sbin/rsyslogd -n -iNONE
+snap_da+ 250 0.0 0.0 1303900 10216 ? Ssl 21:40 0:00 /snap/charmed-postgresql/70/usr/bin/prometheus-postgres-exporter
+root 254 0.0 0.0 15312 7456 ? Ss 21:40 0:00 /lib/systemd/systemd-logind
+root 281 0.0 0.0 7760 3508 ? Ss 21:40 0:00 bash /etc/systemd/system/jujud-machine-0-exec-start.sh
+root 294 0.0 0.0 6216 1064 pts/0 Ss+ 21:40 0:00 /sbin/agetty -o -p -- \u --noclear --keep-baud console 115200,38400,9600 vt220
+root 296 0.0 0.0 15420 9240 ? Ss 21:40 0:00 sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups
+root 301 2.2 0.2 895540 97552 ? Sl 21:40 0:13 /var/lib/juju/tools/machine-0/jujud machine --data-dir /var/lib/juju --machine-id 0 --debug
+root 335 0.0 0.0 110084 21336 ? Ssl 21:40 0:00 /usr/bin/python3 /usr/share/unattended-upgrades/unattended-upgrade-shutdown --wait-for-signal
+root 418 0.0 0.0 235452 8128 ? Ssl 21:40 0:00 /usr/libexec/polkitd --no-debug
+root 772 0.4 0.0 4764 1780 ? Ss 21:40 0:02 snapfuse /var/lib/snapd/snaps/snapd_20092.snap /snap/snapd/20092 -o ro,nodev,allow_other,suid
+root 850 0.2 0.1 2058980 33536 ? Ssl 21:40 0:01 /usr/lib/snapd/snapd
+root 1587 0.0 0.0 4780 3264 ? Ss 21:40 0:00 /bin/bash /snap/charmed-postgresql/70/start-patroni.sh
+snap_da+ 1615 1.1 0.1 490500 39308 ? Sl 21:40 0:06 python3 /snap/charmed-postgresql/70/usr/bin/patroni /var/snap/charmed-postgresql/70/etc/patroni/patroni.yaml
+snap_da+ 2582 0.0 0.0 215816 30076 ? S 21:41 0:00 /snap/charmed-postgresql/current/usr/lib/postgresql/14/bin/postgres -D /var/snap/charmed-postgresql/common/var/lib/postgresql --config-file=/var/snap/charmed-postgresql/common/var/lib/postgresql/postgresql.conf --listen_addresses=10.47.228.200 --port=5432 --cluster_name=postgresql --wal_level=logical --hot_standby=on --max_connections=100 --max_wal_senders=10 --max_prepared_transactions=0 --max_locks_per_transaction=64 --track_commit_timestamp=off --max_replication_slots=10 --max_worker_processes=8 --wal_log_hints=on
+snap_da+ 2808 0.0 0.0 215816 10704 ? Ss 21:41 0:00 postgres: postgresql: checkpointer
+snap_da+ 2810 0.0 0.0 215816 10496 ? Ss 21:41 0:00 postgres: postgresql: background writer
+snap_da+ 2811 0.0 0.0 70540 8804 ? Ss 21:41 0:00 postgres: postgresql: stats collector
+snap_da+ 2840 0.0 0.0 217980 21184 ? Ss 21:41 0:00 postgres: postgresql: operator postgres 10.47.228.200(36138) idle
+snap_da+ 2947 0.0 0.0 216716 14736 ? Ss 21:41 0:00 postgres: postgresql: walsender replication 10.47.228.241(45254) streaming 0/A002FA8
+snap_da+ 2952 0.0 0.0 215816 13140 ? Ss 21:41 0:00 postgres: postgresql: walwriter
+snap_da+ 2953 0.0 0.0 216424 10848 ? Ss 21:41 0:00 postgres: postgresql: autovacuum launcher
+snap_da+ 2954 0.0 0.0 215816 9132 ? Ss 21:41 0:00 postgres: postgresql: archiver last was 00000001000000000000000A.partial
+snap_da+ 2955 0.0 0.0 216260 9516 ? Ss 21:41 0:00 postgres: postgresql: logical replication launcher
+snap_da+ 6556 0.0 0.0 216780 14780 ? Ss 21:42 0:00 postgres: postgresql: walsender replication 10.47.228.164(48482) streaming 0/A002FA8
+root 6799 0.0 0.0 39900 31164 ? S 21:42 0:00 /usr/bin/python3 src/cluster_topology_observer.py https://10.47.228.200:8008 /var/snap/charmed-postgresql/current/etc/patroni/ca.pem /usr/bin/juju-run postgresql/0 /var/lib/juju/agents/unit-postgresql-0/charm
+root 9831 0.0 0.0 4780 3204 ? Ss 21:46 0:00 /bin/bash /snap/charmed-postgresql/70/start-pgbackrest.sh
+snap_da+ 9859 0.0 0.0 56152 13584 ? S 21:46 0:00 /snap/charmed-postgresql/70/usr/bin/pgbackrest server --config=/var/snap/charmed-postgresql/70/etc/pgbackrest/pgbackrest.conf
+root 10168 0.0 0.0 16908 10836 ? Ss 21:47 0:00 sshd: ubuntu [priv]
+ubuntu 10171 0.0 0.0 17056 9628 ? Ss 21:47 0:00 /lib/systemd/systemd --user
+ubuntu 10172 0.0 0.0 170148 4728 ? S 21:47 0:00 (sd-pam)
+ubuntu 10234 0.0 0.0 17208 7944 ? R 21:47 0:00 sshd: ubuntu@pts/1
+ubuntu@juju-fd7874-0:~$
+```
+
+The list of running snap/systemd services will depend on configured (enabled) [COS integration](/t/10600) and/or [backup](/t/9683) functionality. The snap service `charmed-postgresql.patroni` must always be active and currently running (the Linux processes `snapd`, `patroni` and `postgres`).
+
+To access PostgreSQL, check the [charm users concept](/t/10798) and request `operator` credentials to use `psql`:
+```shell
+> juju show-unit postgresql/0 | awk '/private-address:/{print $2;exit}'
+10.47.228.200
+
+> juju run postgresql/leader get-password username=operator
+password: rV0Xn4l65KtQsHSq
+
+> juju ssh postgresql/0 bash
+
+> > psql -h 10.47.228.200 -U operator -d postgres -W
+> > Password for user operator: rV0Xn4l65KtQsHSq
+>
+> > postgres=# \l
+> > postgres | operator | UTF8 | C.UTF-8 | C.UTF-8 | operator=CTc/operator +
+> > | | | | | backup=CTc/operator +
+> ...
+```
+Continue troubleshooting your database/SQL related issues from here.
+
+[note type="caution"]
+**Warning**: Do **NOT** manage users, credentials, databases, schema directly. This avoids a split brain situation with the operator and integrated applications.
+[/note]
+
+It is NOT recommended to restart services directly as it might create a split brain situation with operator internal state. If you see the problem with a unit, consider [removing the failing unit and adding a new unit](/t/9689) to recover the cluster state.
+
+As a last resort, [contact us](/t/11852) if you cannot determine the source of your issue.
+
+Also, feel free to improve this document!
+
+
+
+We recommend you do **not** install any additional software. This may affect stability and produce anomalies that are hard to troubleshoot.
+
+Sometimes, however, it is necessary to install some extra troubleshooting software.
+
+Use the common approach:
+```shell
+ubuntu@juju-fd7874-0:~$ sudo apt update && sudo apt install gdb
+...
+Setting up gdb (12.1-0ubuntu1~22.04) ...
+ubuntu@juju-fd7874-0:~$
+```
+
+**Always remove manually installed components at the end of troubleshooting.** Keep the house clean!
\ No newline at end of file
diff --git a/docs/reference/r-contacts.md b/docs/reference/r-contacts.md
new file mode 100644
index 0000000000..8447eab17f
--- /dev/null
+++ b/docs/reference/r-contacts.md
@@ -0,0 +1,18 @@
+# Contact
+
+Charmed PostgreSQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/postgresql-operator/issues/new/choose)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
+[note]
+Our legacy [Mattermost](https://chat.charmhub.io/charmhub/channels/data-platform) channel is read-only until January 31, 2025.
+[/note]
+
+
+Useful links:
+* [Canonical Data Fabric](https://ubuntu.com/data/)
+* [Charmed PostgreSQL](https://charmhub.io/postgresql)
+* [Git sources for Charmed PostgreSQL](https://github.com/canonical/postgresql-operator)
+* [Canonical Data on Launchpad](https://launchpad.net/~data-platform)
+* [Canonical Data on Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com)
+* [Mailing list on Launchpad](https://lists.launchpad.net/data-platform/)
\ No newline at end of file
diff --git a/docs/reference/r-overview.md b/docs/reference/r-overview.md
new file mode 100644
index 0000000000..8392dce767
--- /dev/null
+++ b/docs/reference/r-overview.md
@@ -0,0 +1,25 @@
+# Overview
+
+The Reference section of our documentation contains pages for technical specifications, APIs, release notes, and other reference material for fast lookup.
+
+**In the left sidebar navigation**, you will find the following references:
+| Page | Description |
+|---------------------------|---------------------------------------------------|
+| [Release Notes](/t/11875) | Release notes for major revisions of this charm |
+| [System requirements](/t/11743) | Software and hardware requirements |
+| [Testing](/t/11773) | Software tests (e.g. smoke, unit, performance...) |
+| [Troubleshooting](/t/11864) | Troubleshooting tips and tricks |
+| [Profiles](/t/11974) | Config profiles related to performance |
+| [Plugins/extensions](/t/10946) | Plugins/extensions supported by each charm revision |
+| [Contacts](/t/11863) | Contact information |
+
+
+**In the tabs at the top of the page**, you can find the following automatically generated API references:
+
+| Page | Description |
+|----------------------------------------------------------------------------|---------------------------------------------------------|
+| [Resources](https://charmhub.io/postgresql/resources) | :construction: Under construction |
+| [Integrations](https://charmhub.io/postgresql/integrations) | Integration/relation interfaces supported by this charm |
+| [Libraries](https://charmhub.io/postgresql/libraries) | VM charm library is empty as charm uses [K8s library](https://charmhub.io/postgresql-k8s/libraries/) (more info [here](/t/11857)) |
+| [Configuration](https://charmhub.io/postgresql/configuration) | Application configuration parameters (more info [here](https://juju.is/docs/juju/configuration?&_ga=2.95573596.1153611399.1713171630-773562698.1708605078#heading--application-configuration)) |
+| [Actions](https://charmhub.io/postgresql/actions) | Juju actions supported by this charm |
\ No newline at end of file
diff --git a/docs/reference/r-performance.md b/docs/reference/r-performance.md
new file mode 100644
index 0000000000..49f689d17a
--- /dev/null
+++ b/docs/reference/r-performance.md
@@ -0,0 +1,44 @@
+# Performance and resource allocation
+
+This page covers topics related to measuring and configuring the performance of PostgreSQL
+
+---
+
+
+For performance testing and benchmarking charms, we recommend using the [Charmed Sysbench](https://charmhub.io/sysbench) operator. This is a tool for benchmarking database applications that includes monitoring and CPU/RAM/IO performance measurement.
+
+ Resource allocation
+Charmed PostgreSQL resource allocation can be controlled via the charm's `profile` config option. There are two profiles: `production` and `testing`.
+
+|Value|Description|Details|
+| --- | --- | ----- |
+|`production` (default)|[Maximum performance](https://github.com/canonical/postgresql-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py#L437-L446)| 25% of the available memory for `shared_buffers` and the remain as cache memory (defaults mimic legacy charm behaviour). The `max_connections`=max(4 * os.cpu_count(), 100). Use [pgbouncer](https://charmhub.io/pgbouncer?channel=1/stable) if max_connections are not enough ([reasoning](https://www.percona.com/blog/scaling-postgresql-with-pgbouncer-you-may-need-a-connection-pooler-sooner-than-you-expect/)).|
+|`testing`|[Minimal resource usage](https://github.com/canonical/postgresql-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py#L437-L446)| PostgreSQL 14 defaults. |
+
+[note type="caution"]
+**Note**: Pre-deployed application profile change is planned but currently is NOT supported.
+[/note]
+
+You can set the profile during deployment using the `--config` flag. For example:
+```shell
+juju deploy postgresql --config profile=testing
+```
+You can change the profile using the `juju config` action. For example:
+```shell
+juju config postgresql profile=production
+```
+For a list of all of this charm's config options, see the [Configuration tab](https://charmhub.io/postgresql/configure#profile).
+
+### Juju constraints
+
+The Juju [`--constraints`](https://juju.is/docs/juju/constraint) flag sets RAM and CPU limits for [Juju units](https://juju.is/docs/juju/unit):
+
+```shell
+juju deploy postgresql --constraints cores=8 mem=16G
+```
+
+Juju constraints can be set together with the charm's profile:
+
+```shell
+juju deploy postgresql --constraints cores=8 mem=16G --config profile=testing
+```
\ No newline at end of file
diff --git a/docs/reference/r-plugins-extensions.md b/docs/reference/r-plugins-extensions.md
new file mode 100644
index 0000000000..89c356eb35
--- /dev/null
+++ b/docs/reference/r-plugins-extensions.md
@@ -0,0 +1,64 @@
+# Supported plugins/extensions
+
+The following list contains all plugins/extensions supported by Charmed PostgreSQL in alphabetical order. The **revision** column indicates which charm revision introduced support for the extension.
+
+If you need support for other extensions, feel free to reach out to us on our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
+
+| Plugin/extension name | Revision |
+|--------------------------------|------------------------------------------------------------------------------|
+| `address_standardizer` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `address_standardizer_data_us` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `bloom` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `bool_plperl` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `btree_gin` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `btree_gist` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `citext` | [304+](https://github.com/canonical/postgresql-operator/releases/tag/rev304) |
+| `citext` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `cube` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `debversion` | [304+](https://github.com/canonical/postgresql-operator/releases/tag/rev304) |
+| `dict_int` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `dict_xsyn` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `earthdistance` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `fuzzystrmatch` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `hll` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `hstore` | [304+](https://github.com/canonical/postgresql-operator/releases/tag/rev304) |
+| `hstore` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `hstore` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `hypopg` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `icu_ext` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `intarray` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `ip4r` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `isn` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `jsonb_plperl` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `lo` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `ltree` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `old_snapshot` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `orafce` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `pg_freespacemap` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `pg_similarity` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `pg_trgm` | [304+](https://github.com/canonical/postgresql-operator/releases/tag/rev304) |
+| `pg_trgm` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `pg_trgm` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `pg_visibility` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `pgrowlocks` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `pgstattuple` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `plperl` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `plpython3u` | [304+](https://github.com/canonical/postgresql-operator/releases/tag/rev304) |
+| `pltcl` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `postgis` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `postgis_raster` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `postgis_tiger_geocoder` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `postgis_topology` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `prefix` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `rdkit` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `seg` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `spi` | [348+](https://github.com/canonical/postgresql-operator/releases/tag/rev348) |
+| `tablefunc` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `tcn` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `tds_fdw` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `tsm_system_rows` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `tsm_system_time` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `unaccent` | [304+](https://github.com/canonical/postgresql-operator/releases/tag/rev304) |
+| `unaccent` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
+| `unaccent` | [357+](https://github.com/canonical/postgresql-operator/releases/tag/rev357) |
+| `uuid-ossp` | [347+](https://github.com/canonical/postgresql-operator/releases/tag/rev347) |
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-releases.md b/docs/reference/r-releases-group/r-releases.md
new file mode 100644
index 0000000000..1b02dc7247
--- /dev/null
+++ b/docs/reference/r-releases-group/r-releases.md
@@ -0,0 +1,16 @@
+# Release Notes
+
+Here you will find release notes for the main revisions of this charm that are available in Charmhub [channels](https://juju.is/docs/sdk/channel):
+
+* **`stable`**: production-ready releases
+* **`candidate`, `beta`, `edge`** : [risk channels](https://juju.is/docs/sdk/channel#heading--risk) - new and experimental features. Not recommended for production.
+
+## Revisions:
+
+| Channel | amd64 | arm64 |
+|---------:|:-----:|:-----:|
+| `14/stable` | [429](/t/14067) | [430](/t/14067) |
+| | [363](/t/13124) | - |
+| | [351](/t/12823) | - |
+| | [336](/t/11877) | - |
+| | [288](/t/11876) | - |
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-revision-288.md b/docs/reference/r-releases-group/r-revision-288.md
new file mode 100644
index 0000000000..e168076166
--- /dev/null
+++ b/docs/reference/r-releases-group/r-revision-288.md
@@ -0,0 +1,52 @@
+>Reference > Release Notes > [All revisions](/t/11875) > [Revision 288](/t/11876)
+# Revision 288
+Thursday, April 20, 2023
+
+Dear community,
+
+We'd like to announce that Canonical's newest Charmed PostgreSQL operator for IAAS/VM has been published in the `14/stable` [channel](https://charmhub.io/postgresql?channel=14/stable). :tada:
+
+## Features you can start using today
+* Deploying on VM (tested with LXD, MAAS)
+* Scaling up/down in one simple juju command
+* HA using [Patroni](https://github.com/zalando/patroni)
+* Full backups and restores are supported when using any S3-compatible storage
+* TLS support (using “[tls-certificates](https://charmhub.io/tls-certificates-operator)” operator)
+* DB access outside of Juju using “[data-integrator](https://charmhub.io/data-integrator)”
+* Data import using standard tools e.g. “psql”.
+* Documentation:
+
+
+## Inside the charms:
+
+* Charmed PostgreSQL charm ships the latest PostgreSQL “14.7-0ubuntu0.22.04.1”
+* VM charms [based on our](https://snapcraft.io/publisher/dataplatformbot) SNAP (Ubuntu LTS “22.04” - core22-based)
+* Principal charms supports the latest LTS series “22.04” only.
+* Subordinate charms support LTS “22.04” and “20.04” only.
+
+## Technical notes
+
+ * The new PostgreSQL charm is also a juju interface-compatible replacement for legacy PostgreSQL charms (using legacy interface `pgsql`, via endpoints `db` and `db-admin`).
+However, **it is highly recommended to migrate to the modern interface [`postgresql_client`](https://github.com/canonical/charm-relation-interfaces)** (endpoint `database`).
+ * Please [contact us](#heading--contact) if you are considering migrating from other “legacy” charms not mentioned above.
+* Charmed PostgreSQL follows SNAP track “14”.
+* No “latest” track in use (no surprises in tracking “latest/stable”)!
+ * PostgreSQL charm provide [legacy charm](/t/10690) through “latest/stable”.
+* You can find charm lifecycle flowchart diagrams [here](https://github.com/canonical/postgresql-k8s-operator/tree/main/docs/reference).
+* Modern interfaces are well described in the [Interfaces catalogue](https://github.com/canonical/charm-relation-interfaces) and implemented by [`data-platform-libs`](https://github.com/canonical/data-platform-libs/).
+* Known limitation: PostgreSQL extensions are not yet supported.
+
+
+Charmed PostgreSQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+
+* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/postgresql-operator/issues/new/choose)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
+
+
+
+
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-revision-336.md b/docs/reference/r-releases-group/r-revision-336.md
new file mode 100644
index 0000000000..4c3d98fa3a
--- /dev/null
+++ b/docs/reference/r-releases-group/r-revision-336.md
@@ -0,0 +1,81 @@
+>Reference > Release Notes > [All revisions](/t/11875) > [Revision 336](/t/11877)
+# Revision 336
+Wednesday, October 18, 2023
+
+Dear community,
+
+We'd like to announce that Canonical's newest Charmed PostgreSQL operator for IAAS/VM has been published in the `14/stable` [channel](https://charmhub.io/postgresql?channel=14/stable). :tada:
+
+If you are jumping over several stable revisions, make sure to check [previous release notes](/t/11875) before upgrading to this revision.
+
+## Features you can start using today
+* [Add Juju 3 support](/t/11743) (Juju 2 is still supported) [[DPE-1758](https://warthogs.atlassian.net/browse/DPE-1758)]
+* All secrets are now stored in [Juju secrets](https://juju.is/docs/juju/manage-secrets) [[DPE-1758](https://warthogs.atlassian.net/browse/DPE-1758)]
+* Charm [minor upgrades](/t/12089) and [minor rollbacks](/t/12090) [[DPE-1767](https://warthogs.atlassian.net/browse/DPE-1767)]
+* [Canonical Observability Stack (COS)](https://charmhub.io/topics/canonical-observability-stack) support [[DPE-1775](https://warthogs.atlassian.net/browse/DPE-1775)]
+* [PostgreSQL plugins support](/t/10906) [[DPE-1373](https://warthogs.atlassian.net/browse/DPE-1373)]
+* [Profiles configuration](/t/11974) support [[DPE-2655](https://warthogs.atlassian.net/browse/DPE-2655)]
+* [Logs rotation](/t/12099) [[DPE-1754](https://warthogs.atlassian.net/browse/DPE-1754)]
+* Workload updated to [PostgreSQL 14.9](https://www.postgresql.org/docs/14/release-14-9.html) [[PR#18](https://github.com/canonical/charmed-postgresql-snap/pull/18)]
+* Add '`admin`' [extra user role](https://github.com/canonical/postgresql-operator/pull/199) [[DPE-2167](https://warthogs.atlassian.net/browse/DPE-2167)]
+* New charm '[PostgreSQL Test App](https://charmhub.io/postgresql-test-app)'
+* New documentation:
+ * [Architecture (HLD/LLD)](/t/11857)
+ * [Upgrade section](/t/12086)
+ * [Release Notes](/t/11875)
+ * [Requirements](/t/11743)
+ * [Profiles](/t/11974)
+ * [Users](/t/10798)
+ * [Logs](/t/12099)
+ * [Statuses](/t/10844)
+ * [Development](/t/11862)
+ * [Testing reference](/t/11773)
+ * [Legacy charm](/t/10690)
+ * [Plugins/extensions](/t/10906), [supported](/t/10946)
+ * [Juju 2.x vs 3.x hints](/t/11985)
+ * [Contacts](/t/11863)
+* All the functionality from [the previous revisions](/t/11875)
+
+## Bugfixes
+* [DPE-1624](https://warthogs.atlassian.net/browse/DPE-1624), [DPE-1625](https://warthogs.atlassian.net/browse/DPE-1625) Backup/restore fixes
+* [DPE-1926](https://warthogs.atlassian.net/browse/DPE-1926) Remove fallback_application_name field from relation data
+* [DPE-1712](https://warthogs.atlassian.net/browse/DPE-1712) Enabled the user to fix network issues and rerun stanza related hooks
+* [DPE-2173](https://warthogs.atlassian.net/browse/DPE-2173) Fix allowed units relation data field
+* [DPE-2127](https://warthogs.atlassian.net/browse/DPE-2127) Fixed databases access
+* [DPE-2341](https://warthogs.atlassian.net/browse/DPE-2341) Populate extensions in unit databag
+* [DPE-2218](https://warthogs.atlassian.net/browse/DPE-2218) Update charm libs to get s3 relation fix
+* [DPE-1210](https://warthogs.atlassian.net/browse/DPE-1210), [DPE-2330](https://warthogs.atlassian.net/browse/DPE-2330), [DPE-2212](https://warthogs.atlassian.net/browse/DPE-2212) Open port (ability to expose charm)
+* [DPE-2614](https://warthogs.atlassian.net/browse/DPE-2614) Split stanza create and stanza check
+* [DPE-2721](https://warthogs.atlassian.net/browse/DPE-2721) Allow network access for pg_dump, pg_dumpall and pg_restore
+* [DPE-2717](https://warthogs.atlassian.net/browse/DPE-2717) Copy dashboard changes from K8s and use the correct topology dispatcher
+* [MISC] Copy fixes of DPE-2626 and DPE-2627 from k8s
+* [MISC] Don't fail if the unit is already missing
+* [MISC] More resilient topology observer
+
+Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/postgresql-operator/issues) platforms.
+
+[GitHub Releases](https://github.com/canonical/postgresql-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision.
+
+## Inside the charms
+
+* Charmed PostgreSQL ships the latest PostgreSQL “14.9-0ubuntu0.22.04.1”
+* PostgreSQL cluster manager Patroni updated to "3.0.2"
+* Backup tools pgBackRest updated to "2.47"
+* The Prometheus postgres-exporter is "0.12.1-0ubuntu0.22.04.1~ppa1"
+* VM charms based on [Charmed PostgreSQL](https://snapcraft.io/charmed-postgresql) SNAP (Ubuntu LTS “22.04” - ubuntu:22.04-based)
+* Principal charms supports the latest LTS series “22.04” only.
+* Subordinate charms support LTS “22.04” and “20.04” only.
+
+## Technical notes
+
+* `juju refresh` from the old-stable revision 288 to the current-revision 324 is **NOT** supported!!! The [upgrade](/t/12086) functionality is new and supported for revision 324+ only!
+* Please check additionally [the previously posted restrictions](/t/11876).
+* Ensure [the charm requirements](/t/11743) met
+
+## Contact us
+
+Charmed PostgreSQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+
+* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/postgresql-operator/issues/new/choose)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-revision-351.md b/docs/reference/r-releases-group/r-revision-351.md
new file mode 100644
index 0000000000..1e3648b1ba
--- /dev/null
+++ b/docs/reference/r-releases-group/r-revision-351.md
@@ -0,0 +1,57 @@
+>Reference > Release Notes > [All revisions](/t/11875) > [Revision 351](/t/12823)
+# Revision 351
+January 3, 2024
+
+Dear community,
+
+We'd like to announce that Canonical's newest Charmed PostgreSQL operator for IAAS/VM has been published in the `14/stable` [channel](https://charmhub.io/postgresql?channel=14/stable).
+
+If you are jumping over several stable revisions, make sure to check [previous release notes](/t/11875) before upgrading to this revision.
+
+## Features you can start using today
+
+* [Core] Updated `Charmed PostgreSQL` SNAP image ([PR#291](https://github.com/canonical/postgresql-operator/pull/291))([DPE-3039](https://warthogs.atlassian.net/browse/DPE-3039)):
+ * `Patroni` updated from 3.0.2 to 3.1.2
+ * `Pgbackrest` updated from 2.47 to 2.48
+* [Plugins] [Add 24 new plugins/extension](https://charmhub.io/postgresql/docs/r-plugins-extensions) in ([PR#251](https://github.com/canonical/postgresql-operator/pull/251))
+* [Plugins] **NOTE**: extension `plpython3u` is deprecated and will be removed from [list of supported plugins](/t/10946) soon!
+* [Config] [Add 29 new configuration options](https://charmhub.io/postgresql/configure) in ([PR#239](https://github.com/canonical/postgresql-operator/pull/239))([DPE-1781](https://warthogs.atlassian.net/browse/DPE-1781))
+* [Config] **NOTE:** the config option `profile-limit-memory` is deprecated. Use `profile_limit_memory` (to follow the [naming conventions](https://juju.is/docs/sdk/naming))! ([PR#306](https://github.com/canonical/postgresql-operator/pull/306))([DPE-3096](https://warthogs.atlassian.net/browse/DPE-3096))
+* [Charm] Add Juju Secret labels in ([PR#270](https://github.com/canonical/postgresql-operator/pull/270))([DPE-2838](https://warthogs.atlassian.net/browse/DPE-2838))
+* [Charm] Update Python dependencies in ([PR#293](https://github.com/canonical/postgresql-operator/pull/293))
+* [DB] Add handling of tables ownership in ([PR#298](https://github.com/canonical/postgresql-operator/pull/298))([DPE-2740](https://warthogs.atlassian.net/browse/DPE-2740))
+* ([COS](https://charmhub.io/topics/canonical-observability-stack)) Moved Grafana dashboard legends to the bottom of the graph in ([PR#295](https://github.com/canonical/postgresql-operator/pull/295))([DPE-2622](https://warthogs.atlassian.net/browse/DPE-2622))
+* ([COS](https://charmhub.io/topics/canonical-observability-stack)) Add Patroni COS support ([#261](https://github.com/canonical/postgresql-operator/pull/261))([DPE-1993](https://warthogs.atlassian.net/browse/DPE-1993))
+* [CI/CD] Charm migrated to GitHub Data reusable workflow in ([PR#263](https://github.com/canonical/postgresql-operator/pull/263))([DPE-2789](https://warthogs.atlassian.net/browse/DPE-2789))
+* All the functionality from [the previous revisions](/t/11875)
+
+## Bugfixes
+
+* Fixed enabling extensions when new database is created ([PR#252](https://github.com/canonical/postgresql-operator/pull/252))([DPE-2569](https://warthogs.atlassian.net/browse/DPE-2569))
+* Block the charm if the legacy interface requests [roles](https://discourse.charmhub.io/t/charmed-postgresql-explanations-interfaces-endpoints/10251) ([DPE-3077](https://warthogs.atlassian.net/browse/DPE-3077))
+
+Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/postgresql-operator/issues) platforms.
+[GitHub Releases](https://github.com/canonical/postgresql-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision.
+## Inside the charms
+
+* Charmed PostgreSQL ships the latest PostgreSQL “14.9-0ubuntu0.22.04.1”
+* PostgreSQL cluster manager Patroni updated to "3.2.1"
+* Backup tools pgBackRest updated to "2.48"
+* The Prometheus postgres-exporter is "0.12.1-0ubuntu0.22.04.1~ppa1"
+* VM charms based on [Charmed PostgreSQL](https://snapcraft.io/charmed-postgresql) SNAP (Ubuntu LTS “22.04” - ubuntu:22.04-based) revision 89
+* Principal charms supports the latest LTS series “22.04” only
+* Subordinate charms support LTS “22.04” and “20.04” only
+
+## Technical notes
+
+* Upgrade (`juju refresh`) is possible from this revision 336+
+* Use this operator together with a modern operator "[pgBouncer](https://charmhub.io/pgbouncer?channel=1/stable)"
+* Please check additionally [the previously posted restrictions](/t/11875)
+* Ensure [the charm requirements](/t/11743) met
+
+## Contact us
+
+Charmed PostgreSQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/postgresql-operator/issues/new/choose)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-revision-363.md b/docs/reference/r-releases-group/r-revision-363.md
new file mode 100644
index 0000000000..e3614ea343
--- /dev/null
+++ b/docs/reference/r-releases-group/r-revision-363.md
@@ -0,0 +1,55 @@
+>Reference > Release Notes > [All revisions](/t/11875) > [Revision 363](/t/13124)
+# Revision 363
+February 21, 2024
+
+Dear community,
+
+We'd like to announce that Canonical's newest Charmed PostgreSQL operator for IAAS/VM has been published in the `14/stable` [channel](https://charmhub.io/postgresql?channel=14/stable) :tada:
+
+If you are jumping over several stable revisions, make sure to check [previous release notes](/t/11875) before upgrading to this revision.
+
+## Features you can start using today
+* [CORE] PostgreSQL upgrade 14.9 -> 14.10. ([DPE-3217](https://warthogs.atlassian.net/browse/DPE-3217))
+ * **Note**: It is advisable to REINDEX potentially-affected indexes after installing this update! (See [PostgreSQL changelog](https://changelogs.ubuntu.com/changelogs/pool/main/p/postgresql-14/postgresql-14_14.10-0ubuntu0.22.04.1/changelog))
+* [CORE] Juju 3.1.7+ support ([#2037120](https://bugs.launchpad.net/juju/+bug/2037120))
+* [PLUGINS] pgVector extension/plugin ([DPE-3159](https://warthogs.atlassian.net/browse/DPE-3159))
+* [PLUGINS] New PostGIS plugin ([#312](https://github.com/canonical/postgresql-operator/pull/312))
+* [PLUGINS] More new plugins - [50 in total](/t/10946)
+* [MONITORING] COS Awesome Alert rules ([DPE-3160](https://warthogs.atlassian.net/browse/DPE-3160))
+* [SECURITY] Updated TLS libraries for compatibility with new charms
+ * [manual-tls-certificates](https://charmhub.io/manual-tls-certificates)
+ * [self-signed-certificates](https://charmhub.io/self-signed-certificates)
+ * Any charms compatible with [ tls_certificates_interface.v2.tls_certificates](https://charmhub.io/tls-certificates-interface/libraries/tls_certificates)
+* All functionality from [previous revisions](/t/11875)
+
+## Bugfixes
+
+* [DPE-3199](https://warthogs.atlassian.net/browse/DPE-3199) Stabilized internal Juju secrets management
+* [DPE-3258](https://warthogs.atlassian.net/browse/DPE-3258) Check system identifier in stanza (backups setup stabilization)
+
+Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/postgresql-operator/issues) platforms.
+[GitHub Releases](https://github.com/canonical/postgresql-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision.
+
+## What is inside the charms
+
+* Charmed PostgreSQL ships the latest PostgreSQL `14.10-0ubuntu0.22.04.1`
+* PostgreSQL cluster manager Patroni updated to `v.3.1.2`
+* Backup tools pgBackRest updated to `v.2.48`
+* The Prometheus postgres-exporter is `0.12.1-0ubuntu0.22.04.1~ppa1`
+* VM charms based on [Charmed PostgreSQL](https://snapcraft.io/charmed-postgresql) SNAP (Ubuntu LTS 22.04 - `ubuntu:22.04-based`) revision 96
+* Principal charms supports the latest LTS series 22.04 only
+* Subordinate charms support LTS 22.04 and 20.04 only
+
+## Technical notes
+
+* Starting with this revision (336+), you can use `juju refresh` to upgrade Charmed PostgreSQL
+* Use this operator together with modern [Charmed PgBouncer operator](https://charmhub.io/pgbouncer?channel=1/stable)
+* Please check [the previously posted restrictions](/t/11875)
+* Ensure [the charm requirements](/t/11743) met
+
+## Contact us
+
+Charmed PostgreSQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/postgresql-operator/issues/new/choose)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-revision-429.md b/docs/reference/r-releases-group/r-revision-429.md
new file mode 100644
index 0000000000..2bf0e0e3fa
--- /dev/null
+++ b/docs/reference/r-releases-group/r-revision-429.md
@@ -0,0 +1,88 @@
+>Reference > Release Notes > [All revisions](t/11875) > Revision 429/430
+
+# Revision 429/430
+
+June 28, 2024
+
+Dear community,
+
+We'd like to announce that Canonical's newest Charmed PostgreSQL operator has been published in the 14/stable [channel](https://charmhub.io/postgresql?channel=14/stable) :tada: :
+
+| |AMD64|ARM64|
+|---:|:---:|:---:|
+| Revisions: | 429 | 430 |
+
+[note]
+If you are jumping over several stable revisions, make sure to check [previous release notes](/t/11875) before upgrading to this revision.
+[/note]
+
+## Features you can start using today
+
+* [PostgreSQL upgrade 14.10 → 14.11](https://www.postgresql.org/docs/release/14.11/) [[PR#432](https://github.com/canonical/postgresql-operator/pull/432)]
+ * [check official PostgreSQL release notes!](https://www.postgresql.org/docs/release/14.11/)
+* [New ARM support!](https://charmhub.io/postgresql/docs/r-requirements) [[PR#381](https://github.com/canonical/postgresql-operator/pull/381)]
+* [Add cross-region async replication!](https://charmhub.io/postgresql/docs/h-async-setup) [[PR#452](https://github.com/canonical/postgresql-operator/pull/452)][[DPE-2953](https://warthogs.atlassian.net/browse/DPE-2953)]
+* [Add timescaledb plugin/extension](https://charmhub.io/postgresql/configuration?channel=14/candidate#plugin_timescaledb_enable) [[PR#470](https://github.com/canonical/postgresql-operator/pull/470)]
+* [Add Incremental+Differential backup support](/t/9683) [[PR#479](https://github.com/canonical/postgresql-operator/pull/479)][[DPE-4462](https://warthogs.atlassian.net/browse/DPE-4462)]
+* [Easy performance testing with sysbench](https://charmhub.io/sysbench)
+* [Add COS Tempo tracing support](/t/14521) [[PR#485](https://github.com/canonical/postgresql-operator/pull/485)][DPE-4616](https://warthogs.atlassian.net/browse/DPE-4616)]
+* Internal disable operator mode [[PR#412](https://github.com/canonical/postgresql-operator/pull/412)][[DPE-2469](https://warthogs.atlassian.net/browse/DPE-2469)]
+* Support for subordination with `ubuntu-advantage` [[PR#397](https://github.com/canonical/postgresql-operator/pull/397)][[DPE-3644](https://warthogs.atlassian.net/browse/DPE-3644)]
+* Support for subordination with `landscape-client` [[PR#388](https://github.com/canonical/postgresql-operator/pull/388)][[DPE-3644](https://warthogs.atlassian.net/browse/DPE-3644)]
+* Add retention time for backups [[PR#474](https://github.com/canonical/postgresql-operator/pull/474)][[DPE-4401](https://warthogs.atlassian.net/browse/DPE-4401)]
+* Add `experimental_max_connections` charm config option [[PR#472](https://github.com/canonical/postgresql-operator/pull/472)]
+* All the functionality from [previous revisions](https://charmhub.io/postgresql/docs/r-releases)
+
+## Bugfixes
+
+* [DPE-3882] Speed up charm bootstrap 2-3 times in [PR#413](https://github.com/canonical/postgresql-operator/pull/413)
+* [DPE-3544] Fixed large objects ownership in [PR#349](https://github.com/canonical/postgresql-operator/pull/349)
+* [DPE-3257] Fixed network cut tests in [PR#346](https://github.com/canonical/postgresql-operator/pull/346)
+* [DPE-3202] Architecture-specific snap revision in [PR#345](https://github.com/canonical/postgresql-operator/pull/345)
+* [DPE-3380] Handle S3 relation in primary non-leader unit in [PR#340](https://github.com/canonical/postgresql-operator/pull/340)
+* [DPE-3559] Stabilise restore cluster test in [PR#351](https://github.com/canonical/postgresql-operator/pull/351)
+* [DPE-3591] Fixed shared buffers validation in [PR#361](https://github.com/canonical/postgresql-operator/pull/361)
+* [DPE-4068] Finished test migration from unittest to pytest + reenable secrets [PR#451](https://github.com/canonical/postgresql-operator/pull/451)
+* [DPE-4106] Test legacy and modern endpoints simultaneously in [PR#396](https://github.com/canonical/postgresql-operator/pull/396)
+* [DPE-2674] Convert `test_charm.py` to pytest style testing instead of unit test in [PR#425](https://github.com/canonical/postgresql-operator/pull/425)
+* [DPE-3895] Handle get patroni health exception in [PR#421](https://github.com/canonical/postgresql-operator/pull/421)
+* [DPE-3593] Only check config values against the DB in `on_config_changed` in [PR#395](https://github.com/canonical/postgresql-operator/pull/395)
+* [DPE-3422] Switch to self-signed certificates in [PR#336](https://github.com/canonical/postgresql-operator/pull/336)
+* [DPE-4336] Reset active status when removing extensions dependency block in [PR#467](https://github.com/canonical/postgresql-operator/pull/467)
+* [DPE-4416] Fixed secrets crash for "certificates-relation-changed" after the refresh in [PR#475](https://github.com/canonical/postgresql-operator/pull/475)
+* [DPE-4416] Fetch charm libs to the latest LIBPATCH (dp-libs v36) in [PR#475](https://github.com/canonical/postgresql-operator/pull/475)
+* [DPE-4412] Use TLS CA chain for backups in [PR#484](https://github.com/canonical/postgresql-operator/pull/484)
+* [DPE-4032] Stop exposing passwords on postgresql SQL queries logging in [PR#495](https://github.com/canonical/postgresql-operator/pull/495)
+* [DPE-4453] Fix scale up with S3 and TLS relations in [PR#480](https://github.com/canonical/postgresql-operator/pull/480)
+* [DPE-4598] Handle upgrade of top of the stack Juju leader in [PR#492](https://github.com/canonical/postgresql-operator/pull/492)
+* [DPE-4416] Update rolling-ops lib to version 0.7 in [PR#478](https://github.com/canonical/postgresql-operator/pull/478)
+* [MISC] Suppress oversee users in standby clusters in [PR#507](https://github.com/canonical/postgresql-operator/pull/507)
+* [MISC] Updated snap, charm libs and switch away from psycopg2-binary in [PR#372](https://github.com/canonical/postgresql-operator/pull/372)
+* Added check for replicas encrypted connection in [PR#437](https://github.com/canonical/postgresql-operator/pull/437)
+* Updated `test_landscape_scalable_bundle_db` test in [PR#378](https://github.com/canonical/postgresql-operator/pull/378)
+
+Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/postgresql-operator/issues) platforms.
+[GitHub Releases](https://github.com/canonical/postgresql-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision.
+
+## Inside the charms
+
+* Charmed PostgreSQL ships the latest PostgreSQL `14.11-0ubuntu0.22.04.1`
+* PostgreSQL cluster manager Patroni updated to `3.1.2`
+* Backup tools pgBackRest updated to `2.48`
+* The Prometheus postgres-exporter is `0.12.1-0ubuntu0.22.04.1~ppa1`
+* VM charms based on [Charmed PostgreSQL](https://snapcraft.io/charmed-postgresql) SNAP (Ubuntu LTS `22.04.4`) revision `113`
+* Principal charms supports the latest LTS series 22.04 only
+
+## Technical notes
+
+* Upgrade via `juju refresh` is possible from revision 336+
+* Use this operator together with the modern [Charmed PgBouncer operator](https://charmhub.io/pgbouncer?channel=1/stable)
+* Please check [previously posted restrictions](https://charmhub.io/postgresql/docs/r-releases)
+* Ensure [the charm requirements](/t/11743) met
+
+## Contact us
+
+Charmed PostgreSQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/postgresql-operator/issues)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
\ No newline at end of file
diff --git a/docs/reference/r-software-testing.md b/docs/reference/r-software-testing.md
new file mode 100644
index 0000000000..5c3800c694
--- /dev/null
+++ b/docs/reference/r-software-testing.md
@@ -0,0 +1,81 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.1`
+
+If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# Software testing for charms
+
+Most types of standard [software tests](https://en.wikipedia.org/wiki/Software_testing) are applicable to Charmed PostgreSQL.
+
+This reference addresses the following types:
+
+* [Smoke test](#heading--smoke)
+* [Unit tests](#heading--unit)
+* [Integration tests](#heading--integration)
+* [System test](#heading--system)
+
+---
+ Smoke test
+This type of test ensures that basic functionality works over a short amount of time.
+### Steps
+1. [Set up a `juju v.3.x` environment](/t/9297)
+2. Deploy database with test application
+3. Start "continuous write" test
+
+Example
+
+```shell
+juju add-model smoke-test
+
+juju deploy postgresql --channel 14/edge
+juju add-unit postgresql -n 2 # (optional)
+
+juju deploy postgresql-test-app
+juju integrate postgresql-test-app:first-database postgresql
+
+# Start "continuous write" test:
+juju run postgresql-test-app/leader start-continuous-writes
+juju run postgresql/leader get-password
+
+export user=operator
+export pass=$(juju run postgresql/leader get-password username=${user} | yq '.. | select(. | has("password")).password')
+export relname=first-database
+export ip=$(juju show-unit postgresql/0 --endpoint database | yq '.. | select(. | has("public-address")).public-address')
+export db=$(juju show-unit postgresql/0 --endpoint database | yq '.. | select(. | has("database")).database')
+export relid=$(juju show-unit postgresql/0 --endpoint database | yq '.. | select(. | has("relation-id")).relation-id')
+export query="select count(*) from continuous_writes"
+
+watch -n1 -x juju run postgresql-test-app/leader run-sql dbname=${db} query="${query}" relation-id=${relid} relation-name=${relname}
+
+# OR
+
+watch -n1 -x juju ssh postgresql/leader "psql postgresql://${user}:${pass}@${ip}:5432/${db} -c \"${query}\""
+
+# Watch that the counter is growing!
+```
+
+
+### Expected results
+* `postgresql-test-app` continuously inserts records into the database received through the integration (the table `continuous_writes`).
+* The counters (amount of records in table) are growing on all cluster members
+
+### Tips
+To stop the "continuous write" test, run
+```shell
+juju run postgresql-test-app/leader stop-continuous-writes
+```
+To truncate the "continuous write" table (i.e. delete all records from database), run
+```shell
+juju run postgresql-test-app/leader clear-continuous-writes
+```
+
+ Unit test
+Check the [Contributing guide](https://github.com/canonical/postgresql-operator/blob/main/CONTRIBUTING.md#testing) on GitHub and follow `tox run -e unit` examples there.
+
+ Integration test
+Check the [Contributing guide](https://github.com/canonical/postgresql-operator/blob/main/CONTRIBUTING.md#testing) on GitHub and follow `tox run -e integration` examples there.
+
+ System test
+To perform a system test, deploy [`postgresql-bundle`](https://charmhub.io/postgresql-bundle).
+This charm bundle automatically deploys and tests all the necessary parts at once.
\ No newline at end of file
diff --git a/docs/reference/r-system-requirements.md b/docs/reference/r-system-requirements.md
new file mode 100644
index 0000000000..c9c6b772a6
--- /dev/null
+++ b/docs/reference/r-system-requirements.md
@@ -0,0 +1,35 @@
+# System requirements
+
+The following are the minimum software and hardware requirements to run Charmed PostgreSQL on VM.
+
+## Software
+* Ubuntu 22.04 (Jammy) or later.
+
+The minimum supported Juju versions are:
+
+* 2.9.32+ (older versions are untested).
+* 3.1.7+ (Juju secrets were stabilized in `v.3.1.7`)
+
+[note type="caution"]
+**Note**: Juju 3.1 is supported from the charm revision 315+
+[/note]
+
+## Hardware
+
+Make sure your machine meets the following requirements:
+
+* 8GB of RAM.
+* 2 CPU threads.
+* At least 20GB of available storage.
+
+The charm is based on the [charmed-postgresql snap](https://snapcraft.io/charmed-postgresql). It currently supports:
+* `amd64`
+* `arm64` (from revision 396+)
+
+[Contact us](/t/11863) if you are interested in a new architecture!
+
+## Networking
+* Access to the internet is required for downloading required snaps and charms
+* Only IPv4 is supported at the moment
+ * See more information about this limitation in [this Jira issue](https://warthogs.atlassian.net/browse/DPE-4695)
+ * [Contact us](/t/11863) if you are interested in IPv6!
\ No newline at end of file
diff --git a/docs/tutorial/t-clean-up.md b/docs/tutorial/t-clean-up.md
new file mode 100644
index 0000000000..aba0cdb7e3
--- /dev/null
+++ b/docs/tutorial/t-clean-up.md
@@ -0,0 +1,37 @@
+> [Charmed PostgreSQL VM Tutorial](https://discourse.charmhub.io/t/9707) > 7. Clean up environment
+
+# Clean up your environment
+
+In this tutorial we've successfully deployed PostgreSQL on LXD, added and removed cluster members, added and removed database users, and enabled a layer of security with TLS.
+
+You may now keep your Charmed PostgreSQL VM deployment running and write to the database or remove it entirely using the steps in this page.
+
+
+## Stop your virtual machine
+If you'd like to keep your environment for later, simply stop your VM with
+```shell
+multipass stop my-vm
+```
+
+## Delete your virtual machine
+If you're done with testing and would like to free up resources on your machine, you can remove the VM entirely.
+
+[note type="caution"]
+**Warning**: When you remove VM as shown below, you will lose all the data in PostgreSQL and any other applications inside Multipass VM!
+
+For more information, see the docs for [`multipass delete`](https://multipass.run/docs/delete-command).
+[/note]
+
+**Delete your VM and its data** with
+```shell
+multipass delete --purge my-vm
+```
+
+## Next Steps
+ If you're looking for what to do next, you can:
+- Run [Charmed PostgreSQL on Kubernetes](https://github.com/canonical/postgresql-k8s-operator).
+- Check out our Charmed offerings of [MySQL](https://charmhub.io/mysql) and [Kafka](https://charmhub.io/kafka?channel=edge).
+- Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability)
+- [Report](https://github.com/canonical/postgresql-operator/issues) any problems you encountered.
+- [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform).
+- [Contribute to the code base](https://github.com/canonical/postgresql-operator)
\ No newline at end of file
diff --git a/docs/tutorial/t-deploy.md b/docs/tutorial/t-deploy.md
new file mode 100644
index 0000000000..6ad6594b3e
--- /dev/null
+++ b/docs/tutorial/t-deploy.md
@@ -0,0 +1,141 @@
+> [Charmed PostgreSQL VM Tutorial](/t/9707) > 2. Deploy PostgreSQL
+
+# Deploy Charmed PostgreSQL VM
+
+In this section, you will deploy Charmed PostgreSQL VM, access a unit, and interact with the PostgreSQL databases that exist inside the application.
+
+## Summary
+- [Deploy PostgreSQL](#heading--deploy)
+- [Access PostgreSQL](#heading--access)
+ - [Retrieve credentials](#heading--retrieve-credentials)
+ - [Access PostgreSQL via `psql`](#heading--psql)
+---
+
+ Deploy PostgreSQL
+
+To deploy Charmed PostgreSQL, all you need to do is run
+```shell
+juju deploy postgresql
+```
+
+Juju will now fetch Charmed PostgreSQL VM from [Charmhub](https://charmhub.io/postgresql?channel=14/stable) and deploy it to the LXD cloud. This process can take several minutes depending on how provisioned (RAM, CPU, etc) your machine is.
+
+You can track the progress by running:
+```shell
+juju status --watch 1s
+```
+
+This command is useful for checking the real-time information about the state of a charm and the machines hosting it. Check the [`juju status` documentation](https://juju.is/docs/juju/juju-status) for more information about its usage.
+
+When the application is ready, `juju status` will show something similar to the sample output below:
+```
+Model Controller Cloud/Region Version SLA Timestamp
+tutorial overlord localhost/localhost 3.1.7 unsupported 09:41:53+01:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql active 1 postgresql 14/stable 281 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/0* active idle 0 10.89.49.129
+
+Machine State Address Inst id Series AZ Message
+0 started 10.89.49.129 juju-a8a31d-0 jammy Running
+```
+
+You can also watch juju logs with the [`juju debug-log`](https://juju.is/docs/juju/juju-debug-log) command.
+More info on logging in the [juju logs documentation](https://juju.is/docs/olm/juju-logs).
+
+ Access PostgreSQL
+
+[note type="caution"]
+ **Warning**: This part of the tutorial accesses PostgreSQL via the `operator` user.
+
+**Do not directly interface with the `operator` user in a production environment.**
+
+In a later section about [Integrations,](https://charmhub.io/postgresql-k8s/docs/t-integrations) we will cover how to safely access PostgreSQL by creating a separate user via the [Data Integrator charm](https://charmhub.io/data-integrator)
+[/note]
+
+ Retrieve credentials
+
+Connecting to the database requires that you know the values for `host`, `username` and `password`.
+
+To retrieve these values, run the Charmed PostgreSQL action `get-password`:
+```shell
+juju run postgresql/leader get-password
+```
+Running the command above should output:
+```yaml
+unit-postgresql-0:
+ UnitId: postgresql/0
+ id: "2"
+ results:
+ operator-password:
+ status: completed
+ timing:
+ completed: 2023-03-20 08:42:22 +0000 UTC
+ enqueued: 2023-03-20 08:42:19 +0000 UTC
+ started: 2023-03-20 08:42:21 +0000 UTC
+```
+
+To request a password for a different user, use the option `username`:
+```shell
+juju run postgresql/leader get-password username=replication
+```
+
+The IP address of the unit hosting the PostgreSQL application, also referred to as the "host", can be found with `juju status`:
+```
+...
+Unit Workload Agent Machine Public address Ports Message
+postgresql/0* active idle 0 10.89.49.129
+...
+```
+ Access PostgreSQL via psql
+
+
+To access the units hosting Charmed PostgreSQL, run
+```shell
+juju ssh postgresql/leader
+```
+
+>If at any point you'd like to leave the unit hosting Charmed PostgreSQL K8s, enter `Ctrl+D` or type `exit`.
+
+The easiest way to access PostgreSQL is via the [PostgreSQL interactive terminal `psql`](https://www.postgresql.org/docs/14/app-psql.html), which is already installed here.
+
+To list all available databases, run:
+```shell
+psql --host=10.89.49.129 --username=operator --password --list
+```
+When requested, enter the `` for charm user `operator` that you obtained earlier.
+
+Example output:
+```
+ List of databases
+ Name | Owner | Encoding | Collate | Ctype | Access privileges
+-----------+----------+----------+---------+---------+-----------------------
+ postgres | operator | UTF8 | C.UTF-8 | C.UTF-8 |
+ template0 | operator | UTF8 | C.UTF-8 | C.UTF-8 | =c/operator +
+ | | | | | operator=CTc/operator
+ template1 | operator | UTF8 | C.UTF-8 | C.UTF-8 | =c/operator +
+ | | | | | operator=CTc/operator
+(3 rows)
+```
+
+You can now interact with PostgreSQL directly using [PostgreSQL SQL Queries](https://www.postgresql.org/docs/14/queries.html). For example, entering `SELECT version();` should output something like:
+```
+> psql --host=10.89.49.129 --username=operator --password postgres
+Password:
+psql (14.7 (Ubuntu 14.7-0ubuntu0.22.04.1))
+Type "help" for help.
+
+postgres=# SELECT version();
+ version
+--------------------------------------------------------------------------------------------------------------------------------------
+ PostgreSQL 14.7 (Ubuntu 14.7-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.3.0-1ubuntu1~22.04) 11.3.0, 64-bit
+(1 row)
+```
+
+Feel free to test out any other PostgreSQL queries.
+
+When you’re ready to leave the PostgreSQL shell, you can just type `exit`. This will take you back to the host of Charmed PostgreSQL K8s (`postgresql-k8s/0`). Exit this host by once again typing `exit`. Now you will be in your original shell where you first started the tutorial. Here you can interact with Juju and LXD.
+
+**Next step:** [3. Scale replicas](/t/9705)
\ No newline at end of file
diff --git a/docs/tutorial/t-enable-tls.md b/docs/tutorial/t-enable-tls.md
new file mode 100644
index 0000000000..1f279df490
--- /dev/null
+++ b/docs/tutorial/t-enable-tls.md
@@ -0,0 +1,90 @@
+> [Charmed PostgreSQL VM Tutorial](/t/9707) > 6. Enable encryption with TLS
+
+# Enable encryption with TLS
+
+[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) is a protocol used to encrypt data exchanged between two applications. Essentially, it secures data transmitted over a network.
+
+Typically, enabling TLS internally within a highly available database or between a highly available database and client/server applications requires a high level of expertise. This has all been encoded into Charmed PostgreSQL so that configuring TLS requires minimal effort on your end.
+
+TLS is enabled by integrating Charmed PostgreSQL with the [Self Signed Certificates Charm](https://charmhub.io/self-signed-certificates). This charm centralises TLS certificate management consistently and handles operations like providing, requesting, and renewing TLS certificates.
+
+In this section, you will learn how to enable security in your PostgreSQL deployment using TLS encryption.
+
+[note type="caution"]
+**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
+
+Check [this guide](/t/11664) for an overview of the TLS certificates charms available.
+[/note]
+
+## Summary
+- [Deploy TLS charm](#heading--deploy-tls-charm)
+- [Integrate with PostgreSQL](#heading--integrate-with-postgresql)
+ - Check the TLS certificates in use
+- [Remove TLS certificate](#heading--remove-tls)
+
+---
+
+ Deploy TLS charm
+
+Before enabling TLS on Charmed PostgreSQL VM, we must deploy the `self-signed-certificates` charm:
+```shell
+juju deploy self-signed-certificates --config ca-common-name="Tutorial CA"
+```
+
+Wait until the `self-signed-certificates` is up and active, use `juju status --watch 1s` to monitor the progress:
+```
+Model Controller Cloud/Region Version SLA Timestamp
+tutorial overlord localhost/localhost 3.1.7 unsupported 10:31:40+01:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql active 2 postgresql 14/stable 281 no
+self-signed-certificates active 1 self-signed-certificates stable 72 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/0* active idle 0 10.89.49.129 Primary
+postgresql/1 active idle 1 10.89.49.197
+self-signed-certificates/0* active idle 3 10.89.49.185
+
+Machine State Address Inst id Series AZ Message
+0 started 10.89.49.129 juju-a8a31d-0 jammy Running
+1 started 10.89.49.197 juju-a8a31d-1 jammy Running
+4 started 10.89.49.185 juju-a8a31d-3 jammy Running
+```
+
+ Integrate with PostgreSQL
+
+To enable TLS on Charmed PostgreSQL VM, integrate the two applications:
+```shell
+juju integrate postgresql self-signed-certificates
+```
+
+### Check the TLS certificate in use
+Use `openssl` to connect to the PostgreSQL and check the TLS certificate in use. Note that your leader unit's IP address will likely be different to the one shown below:
+```shell
+> openssl s_client -starttls postgres -connect 10.89.49.129:5432 | grep Issuer
+...
+depth=1 C = US, CN = Tutorial CA
+verify error:num=19:self-signed certificate in certificate chain
+...
+```
+Congratulations! PostgreSQL is now using TLS certificate generated by the external application `self-signed-certificates`.
+
+
+ Remove TLS certificate
+To remove the external TLS, remove the integration:
+```shell
+juju remove-relation postgresql self-signed-certificates
+```
+
+If you once again check the TLS certificates in use via the OpenSSL client, you will see something similar to the output below:
+```shell
+> openssl s_client -starttls postgres -connect 10.89.49.129:5432
+...
+no peer certificate available
+---
+No client certificate CA names sent
+...
+```
+The Charmed PostgreSQL VM application is not using TLS anymore.
+
+**Next step:** [7. Clean up environment](/t/9695)
\ No newline at end of file
diff --git a/docs/tutorial/t-integrate.md b/docs/tutorial/t-integrate.md
new file mode 100644
index 0000000000..81cfb3de31
--- /dev/null
+++ b/docs/tutorial/t-integrate.md
@@ -0,0 +1,167 @@
+>[Charmed PostgreSQL VM Tutorial](https://discourse.charmhub.io/t/9707) > 5. Integrate with other applications
+
+# Integrate with other applications
+
+[Integrations](https://juju.is/docs/sdk/integration), known as "relations" in Juju 2.9, are the easiest way to create a user for PostgreSQL in Charmed PostgreSQL VM.
+
+Integrations automatically create a username, password, and database for the desired user/application. As mentioned earlier in [2. Deploy PostgreSQL](/t/9697) , it is a better practice to connect to PostgreSQL via a specific user rather than the admin user.
+
+In this section, you will integrate your Charmed PostgreSQL to another charmed application.
+
+## Summary
+- [Deploy `data-integrator`](#heading--deploy-data-integrator)
+- [Integrate with PostgreSQL](#heading--integrate-with-postgresq)
+- [Access the related database](#heading--access-related-database)
+- [Remove the user](#heading--remove-user)
+---
+
+ Deploy data-integrator
+
+Before relating to a charmed application, we must first deploy our charmed application. In this tutorial, we will relate to the [Data Integrator charm](https://charmhub.io/data-integrator). This is a bare-bones charm that allows for central management of database users, providing support for different kinds of data platforms (e.g. PostgreSQL, MySQL, MongoDB, Kafka, etc) with a consistent, opinionated and robust user experience.
+
+To deploy `data-integrator`, run
+
+```shell
+juju deploy data-integrator --config database-name=test-database
+```
+The expected output:
+```
+Located charm "data-integrator" in charm-hub, revision 11
+Deploying "data-integrator" from charm-hub charm "data-integrator", revision 11 in channel stable on jammy
+```
+
+Checking the deployment progress using `juju status` will show a `blocked` state for the newly deployed charm:
+```
+Model Controller Cloud/Region Version SLA Timestamp
+tutorial overlord localhost/localhost 3.1.7 unsupported 10:22:13+01:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+data-integrator blocked 1 data-integrator stable 11 no Please relate the data-integrator with the desired product
+postgresql active 2 postgresql 14/stable 281 no
+
+Unit Workload Agent Machine Public address Ports Message
+data-integrator/0* blocked idle 3 10.89.49.179 Please relate the data-integrator with the desired product
+postgresql/0* active idle 0 10.89.49.129
+postgresql/1 active idle 1 10.89.49.197
+
+Machine State Address Inst id Series AZ Message
+0 started 10.89.49.129 juju-a8a31d-0 jammy Running
+1 started 10.89.49.197 juju-a8a31d-1 jammy Running
+3 started 10.89.49.179 juju-a8a31d-3 jammy Running
+```
+The `blocked` state is expected due to not-yet established relation (integration) between applications.
+
+ Integrate with PostgreSQL
+
+Now that the `data-integrator` charm has been set up, we can relate it to PostgreSQL. This will automatically create a username, password, and database for `data-integrator`.
+
+Relate the two applications with:
+```shell
+juju integrate data-integrator postgresql
+```
+Wait for `juju status --watch 1s` to show all applications/units as `active`:
+```
+Model Controller Cloud/Region Version SLA Timestamp
+tutorial overlord localhost/localhost 3.1.7 unsupported 10:22:31+01:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+data-integrator active 1 data-integrator stable 11 no
+postgresql active 2 postgresql 14/stable 281 no
+
+Unit Workload Agent Machine Public address Ports Message
+data-integrator/0* active idle 3 10.89.49.179
+postgresql/0* active idle 0 10.89.49.129 Primary
+postgresql/1 active idle 1 10.89.49.197
+
+Machine State Address Inst id Series AZ Message
+0 started 10.89.49.129 juju-a8a31d-0 jammy Running
+1 started 10.89.49.197 juju-a8a31d-1 jammy Running
+3 started 10.89.49.179 juju-a8a31d-3 jammy Running
+```
+
+To retrieve information such as the username, password, and database, run the command
+```shell
+juju run data-integrator/leader get-credentials
+```
+This should output something like:
+```yaml
+unit-data-integrator-0:
+ UnitId: data-integrator/0
+ id: "20"
+ results:
+ ok: "True"
+ postgresql:
+ database: test-database
+ endpoints: 10.89.49.129:5432
+ password: 136bvw0s7FjJ6mxZ
+ read-only-endpoints: 10.89.49.197:5432
+ username: relation-3
+ version: "14.7"
+ status: completed
+ timing:
+ completed: 2023-03-20 09:22:50 +0000 UTC
+ enqueued: 2023-03-20 09:22:46 +0000 UTC
+ started: 2023-03-20 09:22:50 +0000 UTC
+```
+Note that your hostnames, usernames, and passwords will likely be different.
+
+
+
+Use `endpoints`, `username`, `password` from above to connect newly created database `test-database` on the PostgreSQL server:
+```shell
+> psql --host=10.89.49.129 --username=relation-3 --password test-database
+...
+test-database=> \l
+...
+ test-database | operator | UTF8 | C.UTF-8 | C.UTF-8 | =Tc/operator +
+ | | | | | operator=CTc/operator +
+ | | | | | "relation-3"=CTc/operator
+...
+```
+
+The newly created database `test-database` is also available on all other PostgreSQL cluster members:
+```shell
+> psql --host=10.89.49.197 --username=relation-3 --password --list
+...
+ test-database | operator | UTF8 | C.UTF-8 | C.UTF-8 | =Tc/operator +
+ | | | | | operator=CTc/operator +
+ | | | | | "relation-3"=CTc/operator
+...
+```
+
+When you relate two applications, Charmed PostgreSQL automatically sets up a new user and database for you.
+Note the database name we specified when we first deployed the `data-integrator` charm: `--config database-name=test-database`.
+
+ Remove the user
+
+Removing the integration automatically removes the user that was created when the integration was created. Enter the following to remove the integration:
+```shell
+juju remove-relation postgresql data-integrator
+```
+
+Now try again to connect to the same PostgreSQL you just used in the previous section:
+
+```shell
+> psql --host=10.89.49.129 --username=relation-3 --password --list
+```
+
+This will output an error message like the one shown below:
+```
+psql: error: connection to server at "10.89.49.129", port 5432 failed: FATAL: password authentication failed for user "relation-3"
+```
+This is expected, since this user no longer exists after removing the integration.
+
+Data remains on the server at this stage.
+
+To create a user again, integrate the applications again:
+```shell
+juju integrate data-integrator postgresql
+```
+Re-integrating generates a new user and password:
+```shell
+juju run data-integrator/leader get-credentials
+```
+You can then connect to the database with these new credentials.
+From here you will see all of your data is still present in the database.
+
+**Next step:** [6. Enable TLS](/t/9699)
\ No newline at end of file
diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md
new file mode 100644
index 0000000000..2d24731e03
--- /dev/null
+++ b/docs/tutorial/t-overview.md
@@ -0,0 +1,23 @@
+# Charmed PostgreSQL VM Tutorial
+
+This section of our documentation contains comprehensive, hands-on tutorials to help you learn how to deploy Charmed PostgreSQL K8s and become familiar with its available operations.
+
+## Prerequisites
+
+While this tutorial intends to guide you as you deploy Charmed PostgreSQL K8s for the first time, it will be most beneficial if:
+- You have some experience using a Linux-based CLI
+- You are familiar with PostgreSQL concepts such as replication and users.
+- Your computer fulfills the [minimum system requirements](/t/11743)
+
+## Tutorial contents
+This Charmed PostgreSQL tutorial has the following parts:
+
+| Step | Details |
+| ------- | ---------- |
+| 1. [**Set up the environment**](/t/9709) | Set up a cloud environment for your deployment using [Multipass](https://multipass.run/) with [LXD](https://ubuntu.com/lxd) and [Juju](https://juju.is/).
+| 2. [**Deploy PostgreSQL**](/t/9697) | Learn to deploy Charmed PostgreSQL K8s using a single command and access the database directly.
+| 3. [**Scale the amount of replicas**](/t/9705) | Learn how to enable high availability with a [Patroni](https://patroni.readthedocs.io/en/latest/)-based cluster.
+| 4. [**Manage passwords**](/t/9703) | Learn how to request and change passwords.
+| 5. [**Integrate PostgreSQL with other applications**](/t/9701) | Learn how to integrate with other applications using the Data Integrator Charm, access the integrated database, and manage users.
+| 6. [**Enable TLS encryption**](/t/9699) | Learn how to enable security in your PostgreSQL deployment via TLS.
+| 7. [**Clean-up your environment**](/t/9695) | Free up your machine's resources.
\ No newline at end of file
diff --git a/docs/tutorial/t-passwords.md b/docs/tutorial/t-passwords.md
new file mode 100644
index 0000000000..85ba852744
--- /dev/null
+++ b/docs/tutorial/t-passwords.md
@@ -0,0 +1,91 @@
+> [Charmed PostgreSQL VM Tutorial](https://discourse.charmhub.io/t/9707) > 4. Manage passwords
+
+# Manage passwords
+
+When we accessed PostgreSQL earlier in this tutorial, we needed to use a password manually. Passwords help to secure our database and are essential for security. Over time, it is a good practice to change the password frequently.
+
+In this section, we will go through setting and changing the password for the admin user.
+
+## Summary
+- [Retrieve the operator password](#heading--retrieve-password)
+- [Rotate the operator password](#heading--rotate-password)
+- [Set a new password](#heading--set-new-password)
+ - ...for the operator
+ - ...for another user
+
+---
+
+ Retrieve the operator password
+
+The operator's password can be retrieved by running the `get-password` action on the Charmed PostgreSQL VM application:
+```shell
+juju run postgresql/leader get-password
+```
+Running the command should output:
+```yaml
+unit-postgresql-0:
+ UnitId: postgresql/0
+ id: "14"
+ results:
+ operator-password: eItxBiOYeMf7seSv
+ status: completed
+ timing:
+ completed: 2023-03-20 09:17:51 +0000 UTC
+ enqueued: 2023-03-20 09:17:49 +0000 UTC
+ started: 2023-03-20 09:17:50 +0000 UTC
+```
+
+ Rotate the operator password
+
+You can change the operator's password to a new random password by entering:
+```shell
+juju run postgresql/leader set-password
+```
+Running the command should output:
+```yaml
+unit-postgresql-0:
+ UnitId: postgresql/0
+ id: "16"
+ results:
+ operator-password: npGdNGNGVtu7SO50
+ status: completed
+ timing:
+ completed: 2023-03-20 09:18:11 +0000 UTC
+ enqueued: 2023-03-20 09:18:08 +0000 UTC
+ started: 2023-03-20 09:18:10 +0000 UTC
+```
+The `status: completed` element in the output above indicates that the password has been successfully updated. The new password should be different from the previous password.
+
+ Set a new password
+
+You can set a specific password for any user by running the `set-password` juju action on the leader unit.
+
+### ...for the operator user
+To set a manual password for the operator/admin user, run the following command:
+```shell
+juju run postgresql/leader set-password password=
+```
+where `` is your password of choice.
+
+Example output:
+```yaml
+unit-postgresql-0:
+ UnitId: postgresql/0
+ id: "18"
+ results:
+ operator-password: my-password
+ status: completed
+ timing:
+ completed: 2023-03-20 09:20:06 +0000 UTC
+ enqueued: 2023-03-20 09:20:04 +0000 UTC
+ started: 2023-03-20 09:20:05 +0000 UTC
+```
+
+### ...for another user
+To set a manual password for another user, run the following command:
+```shell
+juju run postgresql/leader set-password username=my-user password=my-password
+```
+Read more about internal operator users [here](/t/10798).
+
+**Next step:** [5. Integrate with other applications](/t/9701)
\ No newline at end of file
diff --git a/docs/tutorial/t-scale.md b/docs/tutorial/t-scale.md
new file mode 100644
index 0000000000..7a3a5427cb
--- /dev/null
+++ b/docs/tutorial/t-scale.md
@@ -0,0 +1,81 @@
+> [Charmed PostgreSQL VM Tutorial](/t/9707) > 3. Scale replicas
+
+# Scale your replicas
+In this section, you will learn to scale your Charmed PostgreSQL by adding or removing juju units.
+
+The Charmed PostgreSQL VM operator uses a [PostgreSQL Patroni-based cluster](https://patroni.readthedocs.io/en/latest/) for scaling. It provides features such as automatic membership management, fault tolerance, and automatic failover. The charm uses PostgreSQL’s [synchronous replication](https://patroni.readthedocs.io/en/latest/replication_modes.html#postgresql-k8s-synchronous-replication) with Patroni.
+
+[note type="caution"]
+This tutorial hosts all replicas on the same machine.
+
+**This should not be done in a production environment.**
+
+To enable high availability in a production environment, replicas should be hosted on different servers to [maintain isolation](https://canonical.com/blog/database-high-availability).
+[/note]
+
+## Summary
+
+- [Add units](#heading--add-units)
+- [Remove units](#heading--remove-units)
+
+---
+
+ Add units
+
+Currently, your deployment has only one juju **unit**, known in juju as the **leader unit**. You can think of this as the database **primary instance**. For each **replica**, a new unit is created. All units are members of the same database cluster.
+
+To add two replicas to your deployed PostgreSQL application, run
+```shell
+juju add-unit postgresql -n 2
+```
+
+You can now watch the scaling process in live using: `juju status --watch 1s`. It usually takes several minutes for new cluster members to be added.
+
+You’ll know that all three nodes are in sync when `juju status` reports `Workload=active` and `Agent=idle`:
+```
+Model Controller Cloud/Region Version SLA Timestamp
+tutorial overlord localhost/localhost 3.1.7 unsupported 10:16:44+01:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql active 3 postgresql 14/stable 281 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/0* active idle 0 10.89.49.129 Primary
+postgresql/1 active idle 1 10.89.49.197
+postgresql/2 active idle 2 10.89.49.175
+
+Machine State Address Inst id Series AZ Message
+0 started 10.89.49.129 juju-a8a31d-0 jammy Running
+1 started 10.89.49.197 juju-a8a31d-1 jammy Running
+2 started 10.89.49.175 juju-a8a31d-2 jammy Running
+```
+
+ Remove units
+
+Removing a unit from the application scales down the replicas.
+
+Before we scale them down, list all the units with `juju status`. You will see three units: `postgresql/0`, `postgresql/1`, and `postgresql/2`. Each of these units hosts a PostgreSQL replica.
+
+To remove the replica hosted on the unit `postgresql/2` enter:
+```shell
+juju remove-unit postgresql/2
+```
+
+You’ll know that the replica was successfully removed when `juju status --watch 1s` reports:
+```
+Model Controller Cloud/Region Version SLA Timestamp
+tutorial overlord localhost/localhost 3.1.7 unsupported 10:17:14+01:00
+
+App Version Status Scale Charm Channel Rev Exposed Message
+postgresql active 2 postgresql 14/stable 281 no
+
+Unit Workload Agent Machine Public address Ports Message
+postgresql/0* active idle 0 10.89.49.129
+postgresql/1 active idle 1 10.89.49.197
+
+Machine State Address Inst id Series AZ Message
+0 started 10.89.49.129 juju-a8a31d-0 jammy Running
+1 started 10.89.49.197 juju-a8a31d-1 jammy Running
+```
+
+**Next step:** [4. Manage passwords](/t/9703)
\ No newline at end of file
diff --git a/docs/tutorial/t-set-up.md b/docs/tutorial/t-set-up.md
new file mode 100644
index 0000000000..dcc0fd5fca
--- /dev/null
+++ b/docs/tutorial/t-set-up.md
@@ -0,0 +1,68 @@
+> [Charmed PostgreSQL K8s Tutorial](/t/9707) > 1. Set up the environment
+
+# Set up the environment
+
+In this step, we will set up a development environment with the required components for deploying Charmed PostgreSQL.
+
+[note]
+Before you start, make sure your machine meets the [minimum system requirements](/t/11743).
+[/note]
+
+## Summary
+
+- [Set up Multipass](#heading--multipass)
+- [Set up Juju](#heading--juju)
+---
+
+ Set up Multipass
+
+[Multipass](https://multipass.run/) is a quick and easy way to launch virtual machines running Ubuntu. It uses the [cloud-init](https://cloud-init.io/) standard to install and configure all the necessary parts automatically.
+
+Install Multipass from the [snap store](https://snapcraft.io/multipass):
+```shell
+sudo snap install multipass
+```
+
+Launch a new VM using the [charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml) cloud-init config:
+```shell
+multipass launch --cpus 4 --memory 8G --disk 50G --name my-vm charm-dev
+```
+
+[note type=""]
+**Note**: All 'multipass launch' parameters are [described here](https://multipass.run/docs/launch-command).
+[/note]
+
+The Multipass [list of commands](https://multipass.run/docs/multipass-cli-commands) is short and self-explanatory. For example, to show all running VMs, just run the command `multipass list`.
+
+As soon as a new VM has started, access it using
+```shell
+multipass shell my-vm
+```
+
+[note]
+**Note**: If at any point you'd like to leave a Multipass VM, enter `Ctrl+D` or type `exit`.
+[/note]
+
+All necessary components have been pre-installed inside VM already, like LXD and Juju. The files `/var/log/cloud-init.log` and `/var/log/cloud-init-output.log` contain all low-level installation details.
+
+ Set up Juju
+
+Let's bootstrap Juju to use the local LXD controller:
+```shell
+juju bootstrap localhost overlord
+```
+
+A controller can work with different [models](https://juju.is/docs/juju/model). Set up a specific model for Charmed PostgreSQL VM named ‘tutorial’:
+```shell
+juju add-model tutorial
+```
+
+You can now view the model you created above by running the command `juju status`. You should see something similar to the following example output:
+```
+Model Controller Cloud/Region Version SLA Timestamp
+tutorial overlord localhost/localhost 3.1.7 unsupported 09:38:32+01:00
+
+Model "admin/tutorial" is empty.
+```
+
+**Next step:** [2. Deploy PostgreSQL](/t/9697)
\ No newline at end of file