[discourse-gatekeeper] Migrate charm docs

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.

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 <<EOF > 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
+```

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 <<EOF > 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  [email protected]      Running
+2        started  10.163.9.15   juju-00edff-2  [email protected]      Running
+5        started  10.163.9.136  juju-00edff-5  [email protected]      Running
+6        started  10.163.9.36   juju-00edff-6  [email protected]      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  
+```

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
+```

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 <k8s_cos_controller>:<cos_model_name>
+```
+
+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 <db_controller>:<opensearch_dashboards_model_name>
+```
+
+To consume offers to be reachable in the current model, run
+
+```shell
+juju consume <k8s_cos_controller>:admin/cos.grafana
+
+juju consume <k8s_cos_controller>:admin/cos.loki
+
+juju consume <k8s_cos_controller>: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 <k8s_cos_controller>:<cos_model_name>
+```

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 <k8s_cos_controller>:<cos_model_name>
+```
+
+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 <db_controller>:<opensearch_dashboards_model_name>
+```
+
+To consume offers to be reachable in the current model, run
+
+```shell
+juju consume <k8s_cos_controller>:admin/cos.grafana
+juju consume <k8s_cos_controller>:admin/cos.loki
+juju consume <k8s_cos_controller>: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 <k8s_cos_controller>:<cos_model_name>
+```

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 <desired_num_of_units>
+```
+
+While scaling down goes as: 
+
+```
+juju remove-unit opensearch-dashboards/<ID>
+```

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
+[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)</br>  Get started - a hands-on introduction to using the Charmed OpenSearch Dashboards operator for new users </br> |  [How-to guides]() </br> 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)