diff --git a/docs/how-to/h-change-credentials.md b/docs/how-to/h-change-credentials.md new file mode 100644 index 00000000..97680134 --- /dev/null +++ b/docs/how-to/h-change-credentials.md @@ -0,0 +1,13 @@ +# Change the kibanaserver password + +Dashboards have a “super-user” called kibanaserver, that is in reality a specific user set in the Opensearch database. + +For this reason, the credentials change doesn’t happen on the Dashboards side, rather on the Opensearch side. + +Running the following command on the leader unit changes the kibanaserver password: + +``` +juju run openserach/0 set-password +``` + +The new credentials will be populated for the Dashboards charm. \ No newline at end of file diff --git a/docs/how-to/h-db-connect.md b/docs/how-to/h-db-connect.md new file mode 100644 index 00000000..a53a5760 --- /dev/null +++ b/docs/how-to/h-db-connect.md @@ -0,0 +1,37 @@ +# Connection to Opensearch + +An essential pre-requisite for Dashboards is an Opensearch database. + +Opensearch can be deployed as such: + +``` +juju add-model test + +cat < cloudinit-userdata.yaml +cloudinit-userdata: | + postruncmd: + - [ 'sysctl', '-w', 'vm.max_map_count=262144' ] + - [ 'sysctl', '-w', 'vm.swappiness=0' ] + - [ 'sysctl', '-w', 'net.ipv4.tcp_retries2=5' ] + - [ 'sysctl', '-w', 'fs.file-max=1048576' ] +EOF + +juju model-config --file cloudinit-userdata.yaml + +juju deploy opensearch --channel=2/edge +juju deploy self-signed-certificates + +juju integrate self-signed-certificates opensearch +``` + +Now, on top of a live, healthy database we can deploy the visualization interface: + +``` +juju deploy opensearch-dashboards --channel=2/edge +``` + +…and integrate it with the database: + +``` +juju integrate opensearch opensearch-dashboards +``` \ No newline at end of file diff --git a/docs/how-to/h-deploy.md b/docs/how-to/h-deploy.md new file mode 100644 index 00000000..31b1d858 --- /dev/null +++ b/docs/how-to/h-deploy.md @@ -0,0 +1,62 @@ +# Deploy the Opensearch Dashboards charm + +Please follow the [Tutorial](/t/14119) for detailed instructions on how to deploy the charm on LXD. + +Below is a summary of the commands: + +``` +juju add-model test + +cat < cloudinit-userdata.yaml +cloudinit-userdata: | + postruncmd: + - [ 'sysctl', '-w', 'vm.max_map_count=262144' ] + - [ 'sysctl', '-w', 'vm.swappiness=0' ] + - [ 'sysctl', '-w', 'net.ipv4.tcp_retries2=5' ] + - [ 'sysctl', '-w', 'fs.file-max=1048576' ] +EOF + +juju model-config --file cloudinit-userdata.yaml + +juju deploy opensearch --channel=2/edge +juju deploy self-signed-certificates + +juju relate self-signed-certificates opensearch + +juju deploy opensearch-dashboards --channel=2/edge +juju relate opensearch opensearch-dashboards +juju relate self-signed-certificates opensearch-dashboards # TLS +``` + +As a result, a healthy system should look something like this: + +``` +Model Controller Cloud/Region Version SLA Timestamp +test opensearchctl localhost/localhost 3.1.8 unsupported 02:45:35+02:00 + +App Version Status Scale Charm Channel Rev Exposed Message +opensearch active 2 opensearch 2/edge 87 no +opensearch-dashboards active 1 opensearch-dashboards 2/edge 3 no +self-signed-certificates active 1 self-signed-certificates stable 72 no + +Unit Workload Agent Machine Public address Ports Message +opensearch-dashboards/0* active idle 2 10.163.9.15 +opensearch/3* active idle 5 10.163.9.136 +opensearch/4 waiting idle 6 10.163.9.36 Requesting lock on operation: start +self-signed-certificates/0* active idle 1 10.163.9.165 + +Machine State Address Inst id Base AZ Message +1 started 10.163.9.165 juju-00edff-1 ubuntu@22.04 Running +2 started 10.163.9.15 juju-00edff-2 ubuntu@22.04 Running +5 started 10.163.9.136 juju-00edff-5 ubuntu@22.04 Running +6 started 10.163.9.36 juju-00edff-6 ubuntu@22.04 Running + +Integration provider Requirer Interface Type Message +opensearch-dashboards:dashboard_peers opensearch-dashboards:dashboard_peers dashboard_peers peer +opensearch-dashboards:restart opensearch-dashboards:restart rolling_op peer +opensearch:node-lock-fallback opensearch:node-lock-fallback node_lock_fallback peer +opensearch:opensearch-client opensearch-dashboards:opensearch_client opensearch_client regular +opensearch:opensearch-peers opensearch:opensearch-peers opensearch_peers peer +opensearch:upgrade-version-a opensearch:upgrade-version-a upgrade peer +self-signed-certificates:certificates opensearch:certificates tls-certificates regular +``` \ No newline at end of file diff --git a/docs/how-to/h-encryption.md b/docs/how-to/h-encryption.md new file mode 100644 index 00000000..a7e7cf16 --- /dev/null +++ b/docs/how-to/h-encryption.md @@ -0,0 +1,13 @@ +# TLS support + +First, deploy the self-signed-certificates charm: + +``` +juju deploy self-signed-certificates --config ca-common-name="Tutorial CA" +`````````````````````` + +Then, relate it to the Opensearch Dashboards charm. + +``` +juju relate self-signed-certificates opensearch-dashboards +``` \ No newline at end of file diff --git a/docs/how-to/h-mointoring.md b/docs/how-to/h-mointoring.md new file mode 100644 index 00000000..7405b858 --- /dev/null +++ b/docs/how-to/h-mointoring.md @@ -0,0 +1,94 @@ +# How to enable monitoring (COS) + +[note]All commands are written for juju >= v.3.1.7 [/note] + +## Prerequisites + +* A deployed [Charmed OpenSearch operator with a Charmed Opensearch Dadhboards operator](/t/charmed-opensearch-dashboards-tutorial-deployment/14122) +* A deployed [`cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) + +## Summary + +* [Offer interfaces via the COS controller](#offer-interfaces-via-the-cos-controller) +* [Consume offers via the OpenSearch model](#consume-offers-via-the-opensearch-model) +* [Deploy and integrate Grafana](#deploy-and-integrate-grafana) +* [Connect to the Grafana web interface](#connect-to-the-grafana-web-interface) +--- + +## Offer interfaces via the COS controller + +First, we will switch to the COS K8s environment and offer COS interfaces to be cross-model integrated with the Charmed OpenSearch model. + +To switch to the Kubernetes controller for the COS model, run + +```shell +juju switch : +``` + +To offer the COS interfaces, run + +```shell +juju offer grafana:grafana-dashboard + +juju offer loki:logging + +juju offer prometheus:receive-remote-write +``` + +## Consume offers via the OpenSearch Dashboards model + +Next, we will switch to the Charmed OpenSearch Dashboards model, find offers, and consume them. + +We are currently on the Kubernetes controller for the COS model. To switch to the OpenSearch Dashboards model, run + +```shell +juju switch : +``` + +To consume offers to be reachable in the current model, run + +```shell +juju consume :admin/cos.grafana + +juju consume :admin/cos.loki + +juju consume :admin/cos.prometheus +``` + +## Deploy and integrate Grafana + +First, deploy [grafana-agent](https://charmhub.io/grafana-agent): + +```shell +juju deploy grafana-agent +``` + +Then, integrate (previously known as "[relate](https://juju.is/docs/juju/integration)") it with Charmed OpenSearch: + +```shell +juju integrate grafana-agent grafana + +juju integrate grafana-agent loki + +juju integrate grafana-agent prometheus +``` + +Finally, integrate `grafana-agent` with consumed COS offers: + +```shell +juju integrate grafana-agent-k8s opensearch:grafana-dashboard + +juju integrate grafana-agent-k8s opensearch:logging + +juju integrate grafana-agent-k8s opensearch:metrics-endpoint +``` + +After this is complete, Grafana will show the new dashboard `Charmed OpenSearch Dashboards` and will allow access to Charmed OpenSearch logs on Loki. + +## Connect to the Grafana web interface + +To connect to the Grafana web interface, follow the [Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s?_ga=2.201254254.1948444620.1704703837-757109492.1701777558#heading--browse-dashboards) section of the MicroK8s "Getting started" guide. + +```shell +juju run grafana/leader get-admin-password --model : +``` \ No newline at end of file diff --git a/docs/how-to/h-monitoring.md b/docs/how-to/h-monitoring.md new file mode 100644 index 00000000..c64ea421 --- /dev/null +++ b/docs/how-to/h-monitoring.md @@ -0,0 +1,85 @@ +# How to enable monitoring (COS) + +[note]All commands are written for juju >= v.3.1.7 [/note] + +## Prerequisites + +* A deployed [Charmed OpenSearch operator with a Charmed Opensearch Dashboards operator](/t/14122) +* A deployed [`cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) + +## Summary + +* [Offer interfaces via the COS controller](#offer-interfaces-via-the-cos-controller) +* [Consume offers via the OpenSearch model](#consume-offers-via-the-opensearch-model) +* [Deploy and integrate Grafana](#deploy-and-integrate-grafana) +* [Connect to the Grafana web interface](#connect-to-the-grafana-web-interface) +--- + +## Offer interfaces via the COS controller + +First, we will switch to the COS K8s environment and offer COS interfaces to be cross-model integrated with the Charmed OpenSearch model. + +To switch to the Kubernetes controller for the COS model, run + +```shell +juju switch : +``` + +To offer the COS interfaces, run + +```shell +juju offer grafana:grafana-dashboard +juju offer loki:logging +juju offer prometheus:receive-remote-write +``` + +## Consume offers via the OpenSearch Dashboards model + +Next, we will switch to the Charmed OpenSearch Dashboards model, find offers, and consume them. + +We are currently on the Kubernetes controller for the COS model. To switch to the OpenSearch Dashboards model, run + +```shell +juju switch : +``` + +To consume offers to be reachable in the current model, run + +```shell +juju consume :admin/cos.grafana +juju consume :admin/cos.loki +juju consume :admin/cos.prometheus +``` + +## Deploy and integrate Grafana + +First, deploy [grafana-agent](https://charmhub.io/grafana-agent): + +```shell +juju deploy grafana-agent +``` +Then integrate `grafana-agent` with consumed COS offers: + +```shell +juju integrate grafana-agent grafana +juju integrate grafana-agent loki +juju integrate grafana-agent prometheus +``` + +Finally integrate (previously known as "[relate](https://juju.is/docs/juju/integration)") it with Charmed OpenSearch Dashboards: + +```shell +juju integrate grafana-agent-k8s opensearch-dashboards +``` + +After the integration is complete, Grafana will show the new dashboard `Charmed OpenSearch Dashboards` and will allow access to Charmed OpenSearch Dashboards logs on Loki. + +## Connect to the Grafana web interface + +To connect to the Grafana web interface, follow the [Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s?_ga=2.201254254.1948444620.1704703837-757109492.1701777558#heading--browse-dashboards) section of the MicroK8s "Getting started" guide. + +You can obtain the admin password as follows: + +```shell +juju run grafana/leader get-admin-password --model : +``` \ No newline at end of file diff --git a/docs/how-to/h-scale.md b/docs/how-to/h-scale.md new file mode 100644 index 00000000..53f2399e --- /dev/null +++ b/docs/how-to/h-scale.md @@ -0,0 +1,15 @@ +# Scale up/down the application units + +It’s very easy to increase or decrease the number of units in a Juju system. + +Scaling up goes as: + +``` +juju add-unit opensearch-dashboards -n +``` + +While scaling down goes as: + +``` +juju remove-unit opensearch-dashboards/ +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 827095d1..12daf0f2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,45 @@ +# Charmed OpenSearch Dashboards Documentation +[OpenSearch Dashboards](https://opensearch.org/docs/latest/dashboards/) is a frontend application that lets you visualize data stored in an OpenSearch database. Charmed OpenSearch Dashboard is the adaptation of the OpenSearch Dashboards user interface to the [Juju](https://juju.is/) environment. -# Contents \ No newline at end of file +[OpenSearch](https://opensearch.org/) is a distributed search and analytics engine that supports various use cases, from implementing a search box on a website to analyzing security data for threat detection. + +The OpenSearch Dashboards and OpenSearch operators are available for [physical/virtual machines](https://github.com/canonical/pgbouncer-operator). + + +## In this documentation +| | | +|--|--| +| [Tutorials](/t/introduction/14119)
Get started - a hands-on introduction to using the Charmed OpenSearch Dashboards operator for new users
| [How-to guides]()
Step-by-step guides covering key operations and common tasks | + + +## Project and community +Charmed MongoDB is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback. + +* Check our [Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct) +* Raise software issues or feature requests in [GitHub](https://github.com/canonical/opensearch-dashboards-operator/issues) +* Report security issues through [LaunchPad](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File). +* Meet the community and chat with us on [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) + +## Licensing & Trademark + +The Charmed OpenSearch Dashboards Operator is free software, distributed under the [Apache Software License, version 2.0](https://github.com/canonical/opensearch-dashboards-operator/blob/main/LICENSE). + +All of the software in the OpenSearch project is released under the [Apache Software License, version 2.0](https://github.com/canonical/opensearch-dashboards-operator/blob/main/LICENSE) + +# Contents + +1. [Tutorial](tutorial) + 1. [Introduction](tutorial/t-overview.md) + 1. [1. Set up the environment](tutorial/t-set-up.md) + 1. [2. Deploy](tutorial/t-deploy.md) + 1. [3. Enable TLS](tutorial/t-encryption.md) + 1. [4. Interactive Access](tutorial/t-access.md) + 1. [5. Clean up the environment](tutorial/t-cleanup.md) +1. [How To](how-to) + 1. [Deploy](how-to/h-deploy.md) + 1. [Scale up/down](how-to/h-scale.md) + 1. [Connect to OpenSearch](how-to/h-db-connect.md) + 1. [Change credentials](how-to/h-change-credentials.md) + 1. [Enable TLS](how-to/h-encryption.md) + 1. [Enable Monitoring](how-to/h-monitoring.md) \ No newline at end of file diff --git a/docs/opensearch_dashboard.png b/docs/opensearch_dashboard.png deleted file mode 100755 index ec3afaaf..00000000 Binary files a/docs/opensearch_dashboard.png and /dev/null differ diff --git a/docs/opensearch_dashboard_login.png b/docs/opensearch_dashboard_login.png deleted file mode 100644 index 3b1dbff8..00000000 Binary files a/docs/opensearch_dashboard_login.png and /dev/null differ diff --git a/docs/tutorial/t-access.md b/docs/tutorial/t-access.md new file mode 100644 index 00000000..65edd0d2 --- /dev/null +++ b/docs/tutorial/t-access.md @@ -0,0 +1,94 @@ +# Access Opensearch Dashboards + +Assuming that you have a virtual environment available (as described in Step 1.[Set up a virtual environment](/t/14120), open a browser and type there the following URL: + +```text +http://:5601 +``` + +The address of the unit is available in the juju status output of the opensearch-dashboards unit. For example, in the output from Step 2. [Deploy](/t/14122), this would be `10.163.9.173`. + +You should see something like this: + +![Openserach Dashboards - Multipass Desktop|690x431](upload://eK1uIgM8QPgJHik4IKI7Oyaas59.jpeg) + +## Set up an Opensearch user + +Set up a user using the `data-integrator` [charm](https://charmhub.io/data-integrator). + +At deployment time the Opensearch index (in the example: `index_name`) has to be specified as well. This is an arbitrary, alphanumerical identifier of the users' data space in Opensearch. + +User creation takes affect when integrated against the `opensearch` charm. + +```bash +$ juju deploy data-integrator --config index-name= +$ juju relate data-integrator opensearch +``` + +**Note:** this user will have normal privileges - meaning this user will only have access to the index it owns. + +In case a broader access to the cluster's indices is needed, it is possible to create an admin / privileged user as follows: + +```bash +juju deploy data-integrator admin --config index-name=admin-index --config extra-user-roles="admin" +``` +> :warning: **Note:** Please only create admin users when extremely needed, and handle with special care as authenticating with an admin user grants full access to all indices in the cluster. + + +Retrieve user credentials running + +```bash +juju run data-integrator/0 get-credentials +``` +at the bottom of the output you should see something like: +```bash + password: 8kubD7nbWYZFHPVEzIVmTyqV42I7wHb4 + + username: opensearch-client_15 +``` + +## Create the "index pattern" + +Log in to the Dashboard using these credentials. Clicking the top left icon the main menu will pull down. Select **Management** / **Dashboards Management** here + +![Opensearch Dashboards - Initial view |690x327](upload://3rWRYZPHDmLbuQfOo8sfBBGriMW.png) + +Select **Index patterns** on the next view: + +![Opensearch Dashboards - Index patterns |690x327](upload://lIM735RSOujlM8pUFYFKZctFM8J.png) + +Click on **create index pattern** at the bottom. + +Adding the index name that used for `data-integrator` deployment (in our example: `testing`) as an index pattern enables Dashboard access to the user's Opensearch space. + +![Opensearch Dashboards - Create index pattern|690x327](upload://iExCuxU6jroz8XQX1aDObJwPgCU.png) + +Click on the **Next step** button, and finalize the index pattern creation. + +As a verification, the user's index metadata will display. + +## Add and visualize data + +For test purposes, a simple method could do. Like generating data from the command-line, via the Opensearch API: + +``` +for ID in `seq 1 100` +do + curl -sk -u opensearch-client_15:8kubD7nbWYZFHPVEzIVmTyqV42I7wHb4 \ + -XPUT https://10.4.151.211:9200/testing/_doc/${ID} \ + -H "Content-Type: application/json" \ + -d '{"test": "This is test ${ID}"}' +done +``` + +This is how raw data gets displayed in the Dashboard + +![Opensearch Dashboards - Data|690x327](upload://3P7nmmA1fLTdH4NKt3xzCBfumFX.png) + +## Data Visualization + +Opensearch Dashboards offers a variety of diagrams and data displays. + +Choose **Dashboards** in the main left-side menu, and you will be presented to the selection: + +![Opensearch Dashboards - Visualization](upload://ivcwgbpYgolK5wZQkovYW4tlBs.png) \ No newline at end of file diff --git a/docs/tutorial/t-cleanup.md b/docs/tutorial/t-cleanup.md new file mode 100644 index 00000000..dee2cb4e --- /dev/null +++ b/docs/tutorial/t-cleanup.md @@ -0,0 +1,16 @@ +# Clean up + +In case you may want to remove the Juju model, you should run: + +``` +juju remove-model tutorial --force --timeout 1s +``` + +If it’s the whole multipass instance that you would like to delete, you should execute this command: + +``` +multipass delete --purge my-vm +``` + +* [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform). +* [Contribute to the code base](https://github.com/canonical/opensearch-dashboards-opertor) \ No newline at end of file diff --git a/docs/tutorial/t-deploy.md b/docs/tutorial/t-deploy.md new file mode 100644 index 00000000..66ae6a6b --- /dev/null +++ b/docs/tutorial/t-deploy.md @@ -0,0 +1,71 @@ +# Get OpenSearch Dashboards up and running + +The objective of Opensearch Dashboard is to display the contents of an Opensearch database. This is why a functional Opensearch database is a pre-requisite for the Dashboards application to install successfully. + +So, before going further, let’s set up Charmed Opensearch. Note that Opensearch has a mandatory requirement of TLS support, so we need to deploy it alongside the self-signed-certificates charm and integrate (also known as “relate”) them. + +First, set up a cloud-init YAML and configure the juju model: + +``` +# Configure the model +cat < cloudinit-userdata.yaml +cloudinit-userdata: | + postruncmd: + - [ 'sysctl', '-w', 'vm.max_map_count=262144' ] + - [ 'sysctl', '-w', 'vm.swappiness=0' ] + - [ 'sysctl', '-w', 'net.ipv4.tcp_retries2=5' ] + - [ 'sysctl', '-w', 'fs.file-max=1048576' ] +EOF + +juju model-config --file cloudinit-userdata.yaml +``` + +We can deploy Opensearch with TLS: + +``` +juju deploy opensearch --channel=2/edge -n 2 +juju deploy self-signed-certificates +juju relate self-signed-certificates opensearch +``` + +We can simply add the Opensearch Dashboards charm to this setup by deploying and relating it to Opensearch + +``` +juju deploy opensearch-dashboards --channel=2/edge +juju relate opensearch opensearch-dashboards +``` + +And there we go! +Now if you check the status of your services with `juju status`. +Your output should be similar to the example below: + +``` +Model Controller Cloud/Region Version SLA Timestamp +test opensearchctl localhost/localhost 3.1.8 unsupported 23:40:32+02:00 + +App Version Status Scale Charm Channel Rev Exposed Message +opensearch active 1 opensearch 2/edge 87 no +opensearch-dashboards active 1 opensearch-dashboards 2/edge 3 no +self-signed-certificates active 1 self-signed-certificates stable 72 no + +Unit Workload Agent Machine Public address Ports Message +opensearch-dashboards/0* active idle 2 10.163.9.173 +opensearch/0* active idle 0 10.163.9.214 9200/tcp +self-signed-certificates/0* active idle 1 10.163.9.76 + +Machine State Address Inst id Base AZ Message +0 started 10.163.9.214 juju-148a0e-0 ubuntu@22.04 Running +1 started 10.163.9.76 juju-148a0e-1 ubuntu@22.04 Running +2 started 10.163.9.173 juju-148a0e-2 ubuntu@22.04 Running +``` + +**Note**: in case you would like to verify the integrations as well, you can add the flag `--relations`. +``` +$ juju status --relations +``` + +Alternatively, if you want to monitor your system (with a view updating every second): + +``` +$ juju status --watch 1s +``` \ No newline at end of file diff --git a/docs/tutorial/t-encryption.md b/docs/tutorial/t-encryption.md new file mode 100644 index 00000000..7e5933f8 --- /dev/null +++ b/docs/tutorial/t-encryption.md @@ -0,0 +1,9 @@ +# Enable TLS encryption + +Charmed Opensearch Dashboads supports HTTPS connections. Configuration is similar to what we have seen for Opensearch – we just need to relate the Dashboards charm against the TLS charm: + +``` +juju relate self-signed-certificates opensearch-dashboards +``` + +Once the two charms are successfully related, you should be able to access the same URL now using HTTPS. \ No newline at end of file diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md new file mode 100644 index 00000000..7cf711b5 --- /dev/null +++ b/docs/tutorial/t-overview.md @@ -0,0 +1,13 @@ +# Introduction + +This tutorial guides you through how to get Charmed Opensearch Dashboards up and running. It also provides a quick introduction to the following: + +* Set up an environment using [Multipass](https://multipass.run/) with [LXD](https://ubuntu.com/lxd) and [Juju](https://juju.is/). +* Deploy Opensearch Dashboards using a single command. +* Configure TLS certificate equally simple. + +This tutorial focuses on Opensearch Dashboards deployment, assuming that you have familiarity with: + +* Basic terminal commands. +* Opensearch and Opensearch Dashboards concepts +* The [Charmed Opensearch Operator](https://charmhub.io/opensearch) \ No newline at end of file diff --git a/docs/tutorial/t-set-up.md b/docs/tutorial/t-set-up.md new file mode 100644 index 00000000..311e9e0b --- /dev/null +++ b/docs/tutorial/t-set-up.md @@ -0,0 +1,89 @@ +# Set up the environment + +In this section, you will set up your environment by: +* installing and setting up Multipass +* installing Juju and boostrapping LXD +* setting up a graphical interface with Multipass +--- + +## Install and set up Multipass + + +[Multipass](https://multipass.run/) is a quick and easy way to launch virtual machines running Ubuntu. It uses the “[cloud-init](https://cloud-init.io/)” standard to install and configure all the necessary parts automatically. + +Installation of Multipass from [Snap](https://snapcraft.io/multipass) and launching a new VM using “[charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml)” cloud-init config goes as: + +``` +sudo snap install multipass && \ + +multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs +``` + +(The full set of launch parameters is described[ here](https://multipass.run/docs/launch-command).) + +Multipass [commands](https://multipass.run/docs/multipass-cli-commands) are generally short and intuitive. For example, to show all running VMs: + +``` +multipass list +``` + +When the new VM is up and running, connect using: + +``` +multipass shell my-vm +``` + +You can exit the Multipass VM using Ctrl + D or the exit command. + +## Install and set up Juju + +The next step is to install Juju and initialize [LXD](http://containers) (a lightweight container hypervisor). + +``` +sudo snap install juju --classic --channel=3.1/stable +sudo snap install lxd +lxd init --auto +``` + +(Files `/var/log/cloud-init.log and /var/log/cloud-init-output.log` contain all low-level installation details). + +Now that LXD and Juju are installed, the next step is to bootstrap Juju to use local LXD: + +``` +juju bootstrap localhost overlord +``` + +The controller can work with different models. Most applications such as Opensearch or Opensearch Dashboards. To set up a new “model” called tutorial, run: + +``` +juju add-model tutorial +``` + +You can now view the model you created above by entering the command juju status. You should see something similar to the following output: +``` +Model Controller Cloud/Region Version SLA Timestamp +tutorial overlord localhost/localhost 3.1.6 unsupported 23:20:53+01:00 + +Model "admin/tutorial" is empty. +``` + +## Set up a graphical interface + +There are graphical interfaces available for multipass (see more details in the [Multipass Graphical Interface chapter](https://multipass.run/docs/set-up-a-graphical-interface)). + +We recommend to use rdp: + +``` +sudo apt install ubuntu-desktop xrdp remmina-plugin-rdp remmina +sudo passwd ubuntu # Set password here +``` + +Now you should be able to connect using the IP of the earlier multipass list command: + +``` +remmina -c rdp:// +``` + +If the environment comes up with a small resolution, use this great [Stackoverflow suggestion](https://askubuntu.com/questions/914775/remmina-scale-resolution-when-connect-from-ubuntu-to-windows-10). + +Note that after the graphical setup you may be instructed to restart the multipass instance. You probably want to do this before installing the services within (as some may require re-initialization after a reboot otherwise). \ No newline at end of file