Merge ~mthaddon/charm-k8s-mattermost/+git/charm-k8s-mattermost:user-focused into charm-k8s-mattermost:master

[Tom Haddon]

Make the README more end-user focused, and switch to a specific image version, clarifying how upgrades are initiated

Make the README more end-user focused, and switch to a specific image version, clarifying how upgrades are initiated

[🤖 Canonical IS Merge Bot (canonical-is-mergebot)]

This merge proposal is being monitored by mergebot. Change the status to Approved to merge.

[Thomas Cuthbert (tcuthbert)]

LGTM +1

review: Approve

[🤖 Canonical IS Merge Bot (canonical-is-mergebot)]

Change successfully merged at revision 8600461537ee3410944b52ec841ff0c53fa58f25

diff --git a/README.md b/README.md
index b3e6cbe..0d9a28f 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,22 @@
-# Mattermost charm
+# Mattermost Operator
 
-A juju charm deploying Mattermost, using [a custom-built built image](https://code.launchpad.net/~mattermost-charmers/charm-k8s-mattermost/+git/mattermost-k8s-image-builder),
-configurable to use a PostgreSQL backend.
+A Juju charm deploying and managing Mattermost on Kubernetes, configurable to use a PostgreSQL backend.
 
 ## Overview
 
-This is a k8s workload charm and can only be deployed to to a Juju k8s
-cloud, attached to a controller using `juju add-k8s`.
-
-When visiting a fresh deployment, you will first be asked to create an admin
-account.  Further accounts must be created using this admin account, or by
-setting up an external authentication source, such as SAML.
-
+Mattermost offers both [a Team Edition and an Enterprise Edition](https://mattermost.com/pricing-feature-comparison/).
+This charm supports both, with the default image deploying the Team Edition. Supported
+features include authentication via SAML, Push Notifications, clustering,
+the storage of images and attachments in S3, and a Prometheus exporter for
+performance monitoring. This charm also offers seamless Mattermost version
+upgrades, initiated by switching to an image with a newer version of
+Mattermost than the one currently deployed.
 
 ## Usage
 
+For details on using Kubernetes with Juju [see here](https://juju.is/docs/kubernetes), and for
+details on using Juju with MicroK8s for easy local testing [see here](https://juju.is/docs/microk8s-cloud).
+
 To get started deploying the charm in a test environment within a Juju
 Kubernetes model:
 
@@ -23,122 +25,10 @@ Kubernetes model:
     juju add-relation mattermost postgresql:db
     juju expose mattermost
 
-## Local Development
-
-Notes for deploying a test setup locally using MicroK8s:
-
-    sudo snap install juju --classic
-    sudo snap install juju-wait --classic
-    sudo snap install microk8s --classic
-    sudo snap alias microk8s.kubectl kubectl
-    sudo snap install charmcraft
-    git clone https://git.launchpad.net/charm-k8s-mattermost
-    make -C charm-k8s-mattermost mattermost.charm
-
-    microk8s.reset  # Warning! Clean slate!
-    microk8s.enable dns dashboard registry storage
-    microk8s.status --wait-ready
-    microk8s.config | juju add-k8s myk8s --client
-
-    juju bootstrap myk8s
-    juju add-model mattermost-test
-    juju deploy ./charm-k8s-mattermost/mattermost.charm mattermost
-    juju wait
-    juju status
-
-The charm will not function without a database, so you will need to
-deploy `cs:postgresql` somewhere.
-
-If PostgreSQL is deployed in the same model you plan to use for
-Mattermost, simply use `juju relate mattermost postgresql:db`.  (This
-deployment style is recommended for testing purposes only.)
-
-Cross-model relations are also supported.  Create a suitable model on
-a different cloud, for example, LXD or OpenStack.
-
-    juju switch database
-    juju deploy cs:postgresql
-    juju offer postgresql:db
-
-In most k8s deployments, traffic to external services from worker pods
-will be SNATed by some part of the infrastructure.  You will need to
-know what the source addresses or address range is for the next step.
-
-    juju switch mattermost-test
-    juju find-offers  # note down offer URL; example used below:
-    juju relate mattermost admin/database.postgresql --via 10.9.8.0/24
-
-(In the case of PostgreSQL, `--via` is needed so that the charm can
-configure `pga_hba.conf` to let the k8s pods connect to the database.)
-
-## Using a Custom Image
-
-    git clone https://git.launchpad.net/~mattermost-charmers/charm-k8s-mattermost/+git/image-build mattermost-image-build
-    docker build -t localhost:32000/mattermost ./mattermost-image-build
-    docker push localhost:32000/mattermost
-
-Then, to use your new image, either replace the `deploy` step above with
-
-    juju deploy ./charm-k8s-mattermost/mattermost.charm --config mattermost_image_path=localhost:32000/mattermost:latest mattermost
-
-or, if you've already deployed Mattermost:
-
-    juju config mattermost mattermost_image_path=localhost:32000/mattermost:latest
-
-## Authentication
-
-This charm supports configuring [Ubuntu SSO](https://login.ubuntu.com)
-as the authentication method.  This requires the following:
-
- * a Mattermost Enterprise Edition licence to be obtained and activated
- * a SAML config for the Mattermost installation to be added to `login.ubuntu.com`
- * the SAML config will need to have a new certificate generated (refer to "Canonical RT#107985" when requesting this)
-    * this is because the default certificate available via the [SAML metadata URL](https://login.ubuntu.com/+saml/metadata) has expired
- * the new certificate to be installed in the Mattermost database (see below)
-
-### Installing the SAML Identity Provider Certificate
-
-Invoke `psql` against the mattermost database on the current primary
-and use the following query to install the certificate:
-
-    INSERT INTO configurationfiles (name, createat, updateat, data)
-        VALUES ('saml-idp.crt', (extract(epoch from now()) * 1000)::bigint ,(extract(epoch from now()) * 1000)::bigint, $$-----BEGIN CERTIFICATE-----
-    [...]
-    -----END CERTIFICATE-----$$);
-
-## Push Notifications
-
-For full information on selecting a push notification server, please
-[consult the Mattermost documentation](https://docs.mattermost.com/administration/config-settings.html#push-notification-server).
-
-## Allowing All Users to Create Personal Access Tokens
-
-Setting the "Enable Personal Access Tokens" option in the System
-Console's "Integrations" panel (or via the `use_canonical_defaults`
-charm setting) does not give all users the ability to use them.
-
-To give access to all new users, add this database trigger:
-
-    BEGIN;
-    CREATE OR REPLACE FUNCTION grant_system_user_access_token_role() RETURNS TRIGGER AS $$
-      BEGIN
-        IF position('system_user_access_token' in NEW.roles) = 0 THEN
-          NEW.roles = NEW.roles || ' system_user_access_token';
-        END IF;
-        RETURN NEW;
-      END;
-    $$
-    LANGUAGE PLPGSQL;
-
-    DROP TRIGGER IF EXISTS before_insert_system_user_grant_system_user_access_token ON users;
-    CREATE TRIGGER before_insert_system_user_grant_system_user_access_token
-        BEFORE INSERT ON users
-        FOR EACH ROW WHEN ( NEW.roles = 'system_user' )
-        EXECUTE FUNCTION grant_system_user_access_token_role();
-    COMMIT;
-
-And to update all existing users, run this query:
+Once the deployment has completed and the "mattermost" workload state in `juju
+status` has changed to "active" you can visit http://${mattermost_ip}:8065 in a browser and log in to
+your Mattermost instance, and you'll be presented with a screen to create an
+initial admin account. Further accounts must be created using this admin account, or by
+setting up an external authentication source, such as SAML.
 
-    UPDATE users
-        SET roles = 'system_user system_user_access_token'
-        WHERE roles = 'system_user';
+For further details, [see here](https://charmhub.io/mattermost/docs).
diff --git a/config.yaml b/config.yaml
index 34ac0a8..d25ac01 100644
--- a/config.yaml
+++ b/config.yaml
@@ -39,8 +39,10 @@ options:
         description: |
           The location of the image to use, e.g. "registry.example.com/mattermost:v1".
 
+          Switching to a newer image version will initiate an upgrade of Mattermost.
+
           This setting is required.
-        default: mattermostcharmers/mattermost:edge
+        default: mattermostcharmers/mattermost:5.29.0
     mattermost_image_username:
         type: string
         description: |
diff --git a/metadata.yaml b/metadata.yaml
index ad496a5..75f7830 100644
--- a/metadata.yaml
+++ b/metadata.yaml
@@ -1,10 +1,9 @@
 name: mattermost
-summary: Mattermost charm
+summary: Mattermost is a flexible, open source messaging platform that enables secure team collaboration.
 docs: https://discourse.charmhub.io/t/mattermost-documentation-overview/3758
 maintainers:
   - launchpad.net/~canonical-is-sre
 description: |
-  A charm which deploys Mattermost on kubernetes.
   Mattermost is a flexible, open source messaging platform that enables
   secure team collaboration.
   https://mattermost.com