-
Notifications
You must be signed in to change notification settings - Fork 5
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.
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
chore(docs): Update tutorial #296
Open
alithethird
wants to merge
4
commits into
main
Choose a base branch
from
tutorial-update
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -9,18 +9,27 @@ | |
In this tutorial, we'll go through each step of the process to get a basic Discourse deployment. | ||
|
||
## Requirements | ||
- 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). | ||
|
||
* 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`. | ||
For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju). | ||
|
||
## 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 | ||
|
@@ -30,92 +39,128 @@ 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: | ||
juju trust nginx-ingress-integrator --scope=cluster | ||
``` | ||
To check if RBAC is enabled run the following command: | ||
```bash | ||
microk8s status | grep rbac | ||
``` | ||
If it is enabled, then the output should be like the following: | ||
```bash | ||
rbac # (core) Role-Based Access Control for authorisation | ||
``` | ||
If the output is empty then RBAC is not enabled. | ||
|
||
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): | ||
|
||
```bash | ||
juju trust nginx-ingress-integrator --scope=cluster | ||
``` | ||
Then you need to integrate the charm with Nginx Ingress Integrator: | ||
```bash | ||
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 Discourse 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 -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" | 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 discourse-k8s` line from the `/etc/hosts` file. | ||
erinecon marked this conversation as resolved.
Show resolved
Hide resolved
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This step is confusing since Multipass is not a requirement.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same for other mentions to Multipass VM.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We are adding Multipass VM to the tutorials to simplify it for beginners. @erinecon should we add Multipass as a requirement? The tutorial doesn't necessarily need Multipass but we use Multipass in the tutorial to keep it simple to set up.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Multipass is set up if the reader follows the instructions in Set up / Tear down your test environment. So I guess that the requirements can be clearer, i.e., instead of "Juju 3 installed and bootstrapped to a MicroK8s controller" the line could read "A Multipass VM with Juju 3 installed and bootstrapped to a MicroK8s controller."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Or, if we want to leave the possibility open to not use a Multipass VM, then we could update the requirement to say "Juju 3 installed and bootstrapped to a MicroK8s controller. You can accomplish this process by using a Multipass VM as outlined in this guide: Set up / Tear down your test environment"