Mattermost docs - Tutorial - Deploy the Mattermost charm for the first time

charm
,
1

Deploy the Mattermost charm for the first time

What you’ll do

The Mattermost k8s charm helps deploy a horizontally scalable Mattermost application with ease. This tutorial will walk you through each step of deployment to get a basic Mattermost 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 using a Multipass VM as outlined in this guide: Set up / Tear down your test environment
  • NGINX Ingress Controller. If you’re using MicroK8s, this can be done by running the command microk8s enable ingress. For more details, see Addon: Ingress.

For more information about how to install Juju, see Get started with Juju.

:warning: When using a Multipass VM, make sure to replace 127.0.0.1 IP addresses with the VM IP in steps that assume you’re running locally. To get the IP address of the Multipass instance run multipass info my-juju-vm.

Steps

Shell into the Multipass VM

NOTE: If you’re working locally, you can skip this step.

To be able to work inside the Multipass VM first you need to log in with the following command:

multipass shell my-juju-vm

Add a Juju model for the tutorial

To manage resources effectively and to separate this tutorial’s workload from your usual work, create a new model in the MicroK8s controller using the following command:

juju add-model mattermost-tutorial

Deploy the Mattermost charm

Since Mattermost requires connections to PostgreSQL, you’ll deploy it too. For more information, see Charm Architecture.

Deploy the charms:

juju deploy mattermost-k8s
juju deploy postgresql-k8s --trust

Deploy and enable TLS certificates for PostgreSQL connections:

juju deploy tls-certificates-operator

Integrate with the TLS Cerfiticates k8s charm the PostgreSQL k8s charm

You need to configure TLS Certificates Charm to use a self-signed certificates. We will use self-signed certificates for the purposes of this tutorial.

juju config tls-certificates-operator generate-self-signed-certificates="true" ca-common-name="Test CA"

You need to integrate PostgreSQL k8s charm with TLS Certificates charm and Mattermost k8s charm.

juju integrate postgresql-k8s tls-certificates-operator
juju integrate mattermost-k8s postgresql-k8s:db

Run juju status to see the current status of the deployment. The output will look similar to the following:

Model                Controller          Cloud/Region        Version  SLA          Timestamp
mattermost-tutorial  microk8s-localhost  microk8s/localhost  3.5.3    unsupported  20:19:24Z

App                        Version                         Status  Scale  Charm                      Channel        Rev  Address         Exposed  Message
mattermost-k8s             .../mattermost:v8.1.3-20.04...  active      1  mattermost-k8s             latest/stable   27  10.152.183.136  no
postgresql-k8s             14.12                           active      1  postgresql-k8s             14/stable      381  10.152.183.108  no
tls-certificates-operator                                  active      1  tls-certificates-operator  latest/stable   22  10.152.183.192  no

Unit                          Workload  Agent  Address       Ports     Message
mattermost-k8s/0*             active    idle   10.1.200.151  8065/TCP
postgresql-k8s/0*             active    idle   10.1.200.149            Primary
tls-certificates-operator/0*  active    idle   10.1.200.150

The deployment is finished when the Application status shows “Active”.

Login to Mattermost

We should now edit /etc/hosts so that the IP address of your ingress controller resolves to the name of the deployed application. Add the following to that file:

127.0.0.1 mattermost-k8s

Once the deployment has completed and the mattermost-k8s workload state in juju status has changed to active you can then visit http://mattermost-k8s 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.

Clean up the environment

Congratulations! You have successfully finished the Mattermost K8s tutorial. You can now remove the model environment that you’ve created using the following command.

juju destroy-model mattermost-tutorial --destroy-storage

If you used Multipass, to remove the Multipass instance you created for this tutorial, use the following command.

multipass delete --purge my-juju-vm

Finally, remove the 127.0.0.1 mattermost-k8s line from the /etc/hosts file.

2
3

Nice tutorial - Found it really useful and got me up and running in no time.

Some comments/Feedback on this page (part of my onboarding tasks):

Deploy and relate database

  • Database relation subtitle is possibly not needed/doesn’t add anything.
  • Comments in the code snippet are possibly more detail than needed for a Getting Started Tutorial?

Login to Mattermost

  • Is the /etc/hosts use really required (and the use of 127.0.0.1)? Wouldn’t it be simpler to show IP in juju status output and then show using this and port as the URL. (Possibly there’s a reason for adding this step that I’m not appreciating).

Cleaning up the environment

  • juju destroy model => juju destroy-model
1 Like
4

Thanks for the feedback!

I’ve removed the “Database relation” heading as suggested and fixed the destroy-model command.

I think the comments in the database relations code snippet are possibly more detail than needed in a getting started tutorial, but I think they help give context on why each command is needed rather than just following them.

In terms of hitting the IP in juju status vs. hitting 127.0.0.1 the reason for that is the IP in juju status is the IP of the workload unit, and while that’s reachable directly when deploying via MicroK8s it wouldn’t be reachable on any large scale kubernetes cluster. People familiar with Kubernetes but not yet familiar with Juju would want to know how to connect via ingress I think rather than hitting the workload pod directly.

4 Likes
5

Hint: do not miss port 8065 to access Mattermost WEB:

firefox http://<juju_mattermost_k8s_app_ip>:8065

6

Hi Alex,

I don’t believe that’s needed? This is a pod spec charm, so it defines an ingress resource, and assuming you follow the instructions and add the IP of your ingress controller to /etc/hosts you can reach the site without having to hit the pod directly (i.e. using ingress).

Can you confirm if that works for you?

Thanks, Tom

7

My post was to highlight the non-standard port “8065” (as no forwarder on 80/443 ports).

I didn’t mention to use pod IP, the application IP should be used with a proper port:

Screenshot from 2023-10-22 11-54-58
Screenshot from 2023-10-22 11-54-581966×491 118 KB

Sure, /etc/hosts trick with localhost will work if (Micro)K8s is nearby… but it can be running on a different host/cloud. :slight_smile:

I hope it helps. Tnx!

8

Hi Alex,

This charm requires the cluster to have the nginx-ingress controller deployed (which Charmed Kubernetes does, for instance, and MicroK8s does when the “ingress” add on is enabled), and will configure an ingress resource for that, so this is why we’re advising people to connect on port 80 to the ingress controller’s IP. The ingress resource will forward connections to the kubernetes service on port 8065.

Thanks, Tom

1 Like