Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(docs): Update tutorial #296

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(docs): Update tutorial #296

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 69 additions & 40 deletions docs/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,25 @@ In this tutorial, we'll go through each step of the process to get a basic Disco

## Requirements

* 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`.
- A laptop or desktop running Ubuntu (or you can use a VM).
Copy link
Contributor

@erinecon erinecon Oct 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest changing this line to "A working station, e.g., a laptop, with amd64 architecture."

- Juju 3 installed and bootstrapped to a MicroK8s controller. You can accomplish this process by following this guide: [Set up / Tear down your test environment](https://juju.is/docs/juju/set-up--tear-down-your-test-environment)
- NGINX Ingress Controller. If you're using [MicroK8s](https://microk8s.io/), this can be done by running the command `microk8s enable ingress`. For more details, see [Addon: Ingress](https://microk8s.io/docs/addon-ingress).

## Steps

### Set up environment

To easily clean up the resources and separate your workload from the contents of this tutorial, set up a new Juju model named `discourse`:
### Shell into the Multipass VM

To be able to work inside the Multipass VM first you need to log in with the following command:
```bash
multipass shell my-juju-vm
```
juju add-model discourse

### Add a Juju model for the tutorial

To easily clean up the resources and separate your workload from the contents of this tutorial, set up a new Juju model named `discourse-tutorial`:

```bash
juju add-model discourse-tutorial
```

### Deploy the charms
Expand All @@ -30,68 +38,67 @@ Discourse requires connections to PostgreSQL and Redis. For more information, se
> NOTE: Discourse requires PostgreSQL extensions to be available in the relation.

Deploy the charms:
```
```bash
juju deploy redis-k8s --channel latest/edge
juju deploy postgresql-k8s --channel 14/stable --trust
juju deploy discourse-k8s
```

Enable the required PostgreSQL extensions:
```
juju config postgresql-k8s plugin_hstore_enable=True
juju config postgresql-k8s plugin_pg_trgm_enable=True
```bash
juju config postgresql-k8s plugin_hstore_enable=True plugin_pg_trgm_enable=True
```

### Integrate the charms
### Integrate with the Redis k8s charm the PostgreSQL k8s charm

Integrate `redis-k8s` and `postgresql-k8s` to `discourse-k8s`:
```
```bash
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:
```
Model Controller Cloud/Region Version SLA Timestamp
discourse microk8s microk8s/localhost 3.1.7 unsupported 12:48:02+02:00
```bash
Model Controller Cloud/Region Version SLA Timestamp
discourse-tutorial microk8s microk8s/localhost 3.5.4 unsupported 14:07:18+03:00

App Version Status Scale Charm Channel Rev Address Exposed Message
discourse-k8s 3.2.0 active 1 discourse-k8s stable 95 10.152.183.175 no
postgresql-k8s 14.10 active 1 postgresql-k8s 14/stable 193 10.152.183.59 no
redis-k8s 7.0.4 active 1 redis-k8s latest/edge 27 10.152.183.46 no
App Version Status Scale Charm Channel Rev Address Exposed Message
discourse-k8s 3.3.0 active 1 discourse-k8s latest/stable 173 10.152.183.231 no
postgresql-k8s 14.12 active 1 postgresql-k8s 14/stable 381 10.152.183.143 no
redis-k8s 7.2.5 active 1 redis-k8s latest/edge 36 10.152.183.188 no

Unit Workload Agent Address Ports Message
discourse-k8s/0* active idle 10.1.44.214
postgresql-k8s/0* active idle 10.1.44.219
redis-k8s/0* active idle 10.1.44.227
discourse-k8s/0* active idle 10.1.32.182
postgresql-k8s/0* active idle 10.1.32.184 Primary
redis-k8s/0* active idle 10.1.32.181

Integration provider Requirer Interface Type Message
discourse-k8s:restart discourse-k8s:restart rolling_op peer
postgresql-k8s:database discourse-k8s:database postgresql_client regular
postgresql-k8s:database-peers postgresql-k8s:database-peers postgresql_peers peer
postgresql-k8s:restart postgresql-k8s:restart rolling_op peer
postgresql-k8s:upgrade postgresql-k8s:upgrade upgrade peer
redis-k8s:redis discourse-k8s:redis redis regular
redis-k8s:redis-peers redis-k8s:redis-peers redis-peers peer
discourse-k8s:restart discourse-k8s:restart rolling_op peer
postgresql-k8s:database discourse-k8s:database postgresql_client regular
postgresql-k8s:database-peers postgresql-k8s:database-peers postgresql_peers peer
postgresql-k8s:restart postgresql-k8s:restart rolling_op peer
postgresql-k8s:upgrade postgresql-k8s:upgrade upgrade peer
redis-k8s:redis discourse-k8s:redis redis regular
redis-k8s:redis-peers redis-k8s:redis-peers redis-peers peer
```
The deployment finishes when all the charms show `Active` states.

Run `kubectl get pods -n discourse` to see the pods that are being created by the charms:
```
Run `kubectl get pods -n discourse-tutorial` to see the pods that are being created by the charms:
```bash
NAME READY STATUS RESTARTS AGE
modeloperator-64c58d675d-csj47 1/1 Running 0 5m30s
modeloperator-c584f6f9f-qf9gr 1/1 Running 0 5m30s
redis-k8s-0 3/3 Running 0 5m22s
discourse-k8s-0 2/2 Running 0 5m1s
postgresql-k8s-0 2/2 Running 0 5m9s
```

### Provide ingress capabilities
### Provide ingress capabilities

In order to expose the charm, the Nginx Ingress Integrator needs to be deployed and integrated with Discourse:

```
```bash
juju deploy nginx-ingress-integrator
# If your cluster has RBAC enabled you'll be prompted to run the following:
#If your cluster has RBAC enabled, you'll be prompted to run the following (If you are working inside the Multipass vm, chances are you have RBAC enabled):
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that adding a way to check for RBAC wouldn't hurt here (microk8s status)

juju trust nginx-ingress-integrator --scope=cluster

juju integrate discourse-k8s nginx-ingress-integrator
Expand All @@ -100,22 +107,44 @@ juju integrate discourse-k8s nginx-ingress-integrator
### Create an admin user and log in

To create an admin user, use the `create-user` action:
```
```bash
juju run discourse-k8s/0 create-user admin=true [email protected]
```
The command will return the password of the created user. Discourse will be deployed with `discourse-k8s` as default hostname. In order to reach it, modify your `/etc/hosts` file so that it points to `127.0.0.1`:
The command will return the password of the created user. Discourse will be deployed with `discourse-k8s` as default hostname.
If you are using a Multipass instance you need to forward the request from your local to the Multipass instance.
First get the Multipass instances IP address. Since the indico is served on the local address of the Multipass VM we need to use the ip address of the VM. To get the IP address of a Multipass instance run the following command:

```bash
ip a | awk '/inet .* ens3/{print $2}' | cut -d'/' -f1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will fail in many cases (for example if not using the qemu backend and instead using the lxd backend in multipass). I would use instead:
ip -4 -j route get 2.2.2.2 | jq -r '.[] | .prefsrc'

```
The result should be something like this:
```bash
10.131.49.76
```

Add the ip address to the /etc/hosts file:
```bash
echo "10.131.49.76 discourse-k8s" >> /etc/hosts
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would change this to: echo "10.131.49.76 discourse-k8s" | sudo tee -a /etc/hosts

```

If you are following the tutorial in your local machine, modify your `/etc/hosts` file so that it points to `127.0.0.1`:

```bash
echo 127.0.0.1 discourse-k8s >> /etc/hosts
```

After that, visit `http://discourse-k8s` to reach Discourse, using the credentials returned from the `create-user` action to login.

### Clean up the environment
### Clean up the environment

Congratulations! You have successfully finished the Discourse tutorial. You can now remove the
Congratulations! You have successfully finished the Discourse tutorial. You can now remove the
model environment that you've created using the following command:

```bash
juju destroy-model discourse-tutorial --destroy-storage
```
juju destroy-model discourse --destroy-storage
To remove the Multipass instance you created for this tutorial, use the following command.
```bash
multipass delete --purge my-juju-vm
```
It is also a good idea to remove the `10.131.49.76 indico.local` line from the `/etc/hosts` file.
Loading