Update tutorial (#290)

* ISD-2258: Update title Move away from "Getting started" and toward convention of "Deploy X charm for the first time" * ISD-2267: What you'll do & Requirements Reformatted the preexisting text into a "What you'll do" section Small changes to the Requirements section * Add headers that separate tutorial steps Moved "set up environment" into its own section * Update tutorial.md Changes for conciseness Add some code blocks Change `relate` to `integrate` * ISD-2282: Clean up environment section --------- Co-authored-by: arturo-seijas <102022572+arturo-seijas@users.noreply.github.com>
canonical · Sep 18, 2024 · 4b7206e · 4b7206e
1 parent 69de27c
commit 4b7206e
Showing 1 changed file with 45 additions and 19 deletions.
diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -1,26 +1,34 @@
-# Getting started
+# Deploy the Discourse charm for the first time
 
-In this tutorial, we'll walk you through the process of deploying the Discourse charm, relating it to the nginx-ingress-integrator charm, the postgresql-k8s charm and the redis-k8s charm, and inspecting the kubernetes resources created.
+## What you'll do
 
-## Requirements
+- Deploy the Discourse charm
+- Integrate with nginx-ingress-integrator, postgresql-k8s and redis-k8s charms
+- Inspect the Kubernetes resources created
 
-You will need:
+In this tutorial, we'll go through each step of the process to get a basic Discourse deployment.
 
-* A laptop or desktop running Ubuntu (or you can use a VM).
-* [Juju and Microk8s](https://juju.is/docs/olm/microk8s) installed. We’ll also want to make sure the ingress add-on is enabled, which we can do by running `microk8s enable ingress`.
+## Requirements
 
-## Deploy this charm
+* A laptop or desktop running Ubuntu (or you can use a VM).
+* Juju and [Microk8s](https://juju.is/docs/olm/microk8s) installed. We’ll also want to make sure the ingress add-on is enabled, which we can do by running `microk8s enable ingress`.
 
-Discourse requires connections to PostgreSQL and Redis, so those will be deployed too and related to the Discourse charm. For more information, see the [Charm Architecture](https://charmhub.io/discourse-k8s/docs/charm-architecture).
+## Steps
 
-> NOTE: Discourse requires PostgreSQL extensions to be available in the relation.
+### Set up environment
 
-All the above charms will the deployed in a new model named `discourse`:
+To easily clean up the resources and separate your workload from the contents of this tutorial, set up a new Juju model named `discourse`:
 
 ```
 juju add-model discourse
 ```
 
+### Deploy the charms
+
+Discourse requires connections to PostgreSQL and Redis. For more information, see the [Charm Architecture](https://charmhub.io/discourse-k8s/docs/charm-architecture).
+
+> NOTE: Discourse requires PostgreSQL extensions to be available in the relation.
+
 Deploy the charms:
 ```
 juju deploy redis-k8s --channel latest/edge
@@ -34,13 +42,15 @@ juju config postgresql-k8s plugin_hstore_enable=True
 juju config postgresql-k8s plugin_pg_trgm_enable=True
 ```
 
-Relate `redis-k8s` and `postgresql-k8s` to `discourse-k8s`:
+### Integrate the charms
+
+Integrate `redis-k8s` and `postgresql-k8s` to `discourse-k8s`:
 ```
-juju relate redis-k8s discourse-k8s
-juju relate discourse-k8s postgresql-k8s
+juju integrate redis-k8s discourse-k8s
+juju integrate discourse-k8s postgresql-k8s
 ```
 
-By running `juju status --relations` the current state of the deployment can be queried, with all the charms eventually reaching `Active`state:
+By running `juju status --relations` the current state of the deployment can be queried:
 ```
 Model      Controller  Cloud/Region        Version  SLA          Timestamp
 discourse  microk8s    microk8s/localhost  3.1.7    unsupported  12:48:02+02:00
@@ -64,6 +74,7 @@ postgresql-k8s:upgrade         postgresql-k8s:upgrade         upgrade
 redis-k8s:redis                discourse-k8s:redis            redis              regular  
 redis-k8s:redis-peers          redis-k8s:redis-peers          redis-peers        peer     
 ```
+The deployment finishes when all the charms show `Active` states.
 
 Run `kubectl get pods -n discourse` to see the pods that are being created by the charms:
 ```
@@ -74,22 +85,37 @@ discourse-k8s-0                  2/2     Running   0          5m1s
 postgresql-k8s-0                 2/2     Running   0          5m9s
 ```
 
-In order to expose the charm, the Nginx Ingress Integrator is to be deployed alongside Discourse to provide ingress capabilities
+### Provide ingress capabilities 
+
+In order to expose the charm, the Nginx Ingress Integrator needs to be deployed and integrated with Discourse:
 
 ```
 juju deploy nginx-ingress-integrator
 # If your cluster has RBAC enabled you'll be prompted to run the following:
 juju trust nginx-ingress-integrator --scope=cluster
 
-juju relate discourse-k8s nginx-ingress-integrator
+juju integrate discourse-k8s nginx-ingress-integrator
 ```
 
-To create an admin user, run:
+### Create an admin user and log in
+
+To create an admin user, use the `create-user` action:
 ```
 juju run discourse-k8s/0 create-user admin=true email=email@example.com
 ```
-The command will return the password of the created user. Discourse will be deployed with `discourse-k8s` as default hostname. In order to reach it, modify your `/etc/hosts` file so that it points to `127.0.0.1`
+The command will return the password of the created user. Discourse will be deployed with `discourse-k8s` as default hostname. In order to reach it, modify your `/etc/hosts` file so that it points to `127.0.0.1`:
 
-`echo 127.0.0.1 discourse-k8s >> /etc/hosts`
+```
+echo 127.0.0.1 discourse-k8s >> /etc/hosts
+```
 
 After that, visit `http://discourse-k8s` to reach Discourse, using the credentials returned from the `create-user` action to login.
+
+### Clean up the environment 
+
+Congratulations! You have successfully finished the Discourse tutorial. You can now remove the 
+model environment that you've created using the following command:
+
+```
+juju destroy-model discourse --destroy-storage
+```