diff --git a/README.md b/README.md index fbb974e9..3f1a39d8 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ fixes and constructive feedback. * [Join our online chat](https://chat.charmhub.io/charmhub/channels/charm-dev) * [Contribute](https://charmhub.io/discourse-k8s/docs/contributing) * [Get started](https://charmhub.io/discourse-k8s/docs/getting-started) + Thinking about using the Discourse Operator for your next project? [Get in touch](https://chat.charmhub.io/charmhub/channels/charm-dev)! --- diff --git a/docs/Reference/.gitkeep b/docs/Reference/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/Tutorial/contributing.md b/docs/Tutorial/contributing.md deleted file mode 100644 index 585b3ea8..00000000 --- a/docs/Tutorial/contributing.md +++ /dev/null @@ -1,35 +0,0 @@ -# Contributing - -This document explains the processes and practices recommended for contributing enhancements to the Discourse operator. - -* Generally, before developing enhancements to this charm, you should consider [opening an issue](https://github.com/canonical/discourse-k8s-operator/issues) explaining your use case. -* If you would like to chat with us about your use-cases or proposed implementation, you can reach us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev) or [Discourse](https://discourse.charmhub.io/). -* Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library will help you a lot when working on new features or bug fixes. -* All enhancements require review before being merged. Code review typically examines - * code quality - * test coverage - * user experience for Juju administrators of this charm. -For more details, check our [contibuting guide](https://github.com/canonical/is-charms-contributing-guide/blob/main/CONTRIBUTING.md). - -## Developing - -For any problems with this charm, please [report bugs here](https://github.com/canonical/discourse-k8s-operator/issues). - -The code for this charm can be downloaded as follows: - -``` -git clone https://github.com/canonical/discourse-k8s-operator -``` - -To run tests, run `tox` from within the charm code directory. - -To build and deploy a local version of the charm, simply run: - -``` -charmcraft pack -# Ensure you're connected to a juju k8s model, assuming you're on amd64 -juju deploy ./discourse-k8s_ubuntu-20.04-amd64.charm -``` -## Canonical Contributor Agreement - -Canonical welcomes contributions to the Discourse Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you’re interested in contributing to the solution. \ No newline at end of file diff --git a/docs/Tutorial/hostname-configuration.md b/docs/Tutorial/hostname-configuration.md deleted file mode 100644 index ece7938a..00000000 --- a/docs/Tutorial/hostname-configuration.md +++ /dev/null @@ -1,17 +0,0 @@ -# Hostname configuration - -This charm exposes the `external_hostname` configuration option to specify the external hostname of the application. - -To expose the application it is recommended to set that configuration option and deploy and relate the [Nginx Ingress Integrator Operator](https://charmhub.io/nginx-ingress-integrator), that will be automatically configured with the values provided by the charm. - -Assuming Discourse is already up and running as `discourse-k8s`, you'll need to run the following commands: -``` -# Configure the external hostname -juju config discourse-k8s external_hostname=discourse.local -# Deploy and relate the Nginx Ingress Integrator charm -juju deploy nginx-ingress-integrator -juju trust nginx-ingress-integrator --scope cluster # if RBAC is enabled -juju relate nginx-ingress-integrator discourse-k8s -``` - -For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure). \ No newline at end of file diff --git a/docs/Explanation/explanation-charm-architecture.md b/docs/explanation/charm-architecture.md similarity index 90% rename from docs/Explanation/explanation-charm-architecture.md rename to docs/explanation/charm-architecture.md index 3ae46dd7..c6f2425d 100644 --- a/docs/Explanation/explanation-charm-architecture.md +++ b/docs/explanation/charm-architecture.md @@ -1,4 +1,4 @@ -# Charm Architecture +# Charm architecture At its core, [Discourse](https://www.discourse.org/) is a [Ruby on Rails](https://rubyonrails.org/) application that integrates with [PostgreSQL](https://www.postgresql.org/) and [Redis](https://redis.io/). @@ -33,9 +33,9 @@ The server is started in HTTP mode (port `3000`) serving all the content. Alongs The workload that this container is running is defined in the [Discourse dockerfile in the charm repository](https://github.com/canonical/discourse-k8s-operator/blob/main/discourse.Dockerfile). -## Docker Images +## OCI images -The image defined in the [Discourse dockerfile](https://github.com/canonical/discourse-k8s-operator/blob/main/discourse.Dockerfile) in the charm repository is published to [Charmhub](https://charmhub.io/), the official repository of charms. +The OCI image is built using [Rockcraft](https://canonical-rockcraft.readthedocs-hosted.com) and defined in the [Rockfile](https://github.com/canonical/discourse-k8s-operator/blob/main/discourse_rock/rockcraft.yaml) in the charm repository. It is then published to [Charmhub](https://charmhub.io/), the official repository for charms. This is done by publishing a resource to Charmhub as described in the [Juju SDK How-to guides](https://juju.is/docs/sdk/publishing). @@ -64,7 +64,7 @@ Loki is an open-source fully-featured logging system. This charms is shipped wit ### Prometheus Prometheus is an open-source systems monitoring and alerting toolkit with a dimensional data model, flexible query language, efficient time series database and modern alerting approach. This charm is shipped with a Prometheus exporter, alerts and support for integrating with the [Prometheus Operator](https://charmhub.io/prometheus-k8s) to automatically scrape the targets. -## Juju Events +## Juju events Accordingly to the [Juju SDK](https://juju.is/docs/sdk/event): "an event is a data structure that encapsulates part of the execution context of a charm". @@ -72,12 +72,12 @@ For this charm, the following events are observed: 1. [_pebble_ready](https://juju.is/docs/sdk/container-name-pebble-ready-event): fired on Kubernetes charms when the requested container is ready. Action: wait for the integrations, and configure the containers. 2. [config_changed](https://juju.is/docs/sdk/config-changed-event): usually fired in response to a configuration change using the GUI or CLI. Action: wait for the integrations, validate the configuration, update Ingress, and restart the containers. -4. [add_admin_user_action](https://charmhub.io/discourse-k8s/actions): fired when add-admin-user action is executed. Action: add an admin user with the provided email and password. -5. [database_relation_joined](https://github.com/canonical/ops-lib-pgsql): PostgreSQLClient custom event for when the connection details to the master database on this relation joins. Action: initialize the database and enable the appropriate extensions. +3. [add_admin_user_action](https://charmhub.io/discourse-k8s/actions): fired when add-admin-user action is executed. Action: add an admin user with the provided email and password. +4. [database_relation_joined](https://github.com/canonical/ops-lib-pgsql): PostgreSQLClient custom event for when the connection details to the master database on this relation joins. Action: initialize the database and enable the appropriate extensions. 5. [master_changed](https://github.com/canonical/ops-lib-pgsql): PostgreSQLClient custom event for when the connection details to the master database on this relation change. Action: update the database connection string configuration and emit config_changed event. -5. [redis_relation_updated](https://github.com/canonical/redis-k8s-operator): Redis Operator custom event for when the relation details have been updated. Action: wait for the integrations and restart the containers. +6. [redis_relation_updated](https://github.com/canonical/redis-k8s-operator): Redis Operator custom event for when the relation details have been updated. Action: wait for the integrations and restart the containers. -## Charm Code Overview +## Charm code overview The `src/charm.py` is the default entry point for a charm and has the DiscourseCharm Python class which inherits from CharmBase. @@ -85,4 +85,4 @@ CharmBase is the base class from which all Charms are formed, defined by [Ops](h See more information in [Charm](https://juju.is/docs/sdk/constructs#heading--charm). -The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them. \ No newline at end of file +The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them. diff --git a/docs/Tutorial/container-configuration.md b/docs/how-to/configure-container.md similarity index 95% rename from docs/Tutorial/container-configuration.md rename to docs/how-to/configure-container.md index e6eaec16..9dc2c817 100644 --- a/docs/Tutorial/container-configuration.md +++ b/docs/how-to/configure-container.md @@ -1,4 +1,4 @@ -# Container configuration +# How to configure the container This charm exposes several configurations to tweak the behaviour of discourse. These can by changes by running `juju config [charm_name] [configuration]=[value]`. Below you can find some of the options that will allow you to modify the charm's behaviour: @@ -6,4 +6,4 @@ This charm exposes several configurations to tweak the behaviour of discourse. T * The developer mails can be set through [developer_emails](https://charmhub.io/discourse-k8s/configure#developer_emails) * Throttle level protections provided by discourse can be changed via [throttle_level](https://charmhub.io/discourse-k8s/configure#throttle_level) -For a comprehensive list of configuration options check the [configuration reference](https://charmhub.io/discourse-k8s/configure). \ No newline at end of file +For a comprehensive list of configuration options check the [configuration reference](https://charmhub.io/discourse-k8s/configure). diff --git a/docs/how-to/configure-hostname.md b/docs/how-to/configure-hostname.md new file mode 100644 index 00000000..e5beefd7 --- /dev/null +++ b/docs/how-to/configure-hostname.md @@ -0,0 +1,49 @@ +# How to configure the hostname + +### Prerequisites + +Deploy and relate [nginx-ingress-integrator](https://charmhub.io/nginx-ingress-integrator) charm. + +``` +juju deploy nginx-ingress-integrator +juju trust nginx-ingress-integrator --scope cluster # if RBAC is enabled +juju relate discourse-k8s nginx-ingress-integrator +``` + +### Configure hostname + +This charm exposes the `external_hostname` configuration option to specify the external hostname of the application. + +To configure a different hostname for Discourse, you can configure the ingress hostname through the +discourse-k8s configuration. + +``` +juju config discourse-k8s external_hostname= +``` + +The output of `juju status` should look similar to the following: + +``` +Model Controller Cloud/Region Version SLA Timestamp +tutorial mk8s microk8s/localhost 2.9.44 unsupported 18:19:34-04:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +discourse-k8s 2.8.14 active 1 discourse-k8s 41 no +nginx-ingress-integrator 25.3.0 active 1 nginx-ingress-integrator latest/stable 81 no Ingress IP(s): 127.0.0.1, Service IP(s): +postgresql-k8s 14.9 active 1 postgresql-k8s 14/edge 145 no Primary +redis-k8s 7.0.4 active 1 redis-k8s latest/edge 26 no + +Unit Workload Agent Address Ports Message +discourse-k8s/0* active idle +nginx-ingress-integrator/0* active idle Ingress IP(s): 127.0.0.1, Service IP(s): +postgresql-k8s/0* active idle Primary +redis-k8s/0* active idle +``` + +Note the Service IP(s): next to nginx-ingress-integrator charm’s Status output. + +Test the ingress by sending a GET request to the service with `Host` headers. + +``` +curl -H "Host: " http:// +``` diff --git a/docs/Tutorial/s3-configuration.md b/docs/how-to/configure-s3.md similarity index 95% rename from docs/Tutorial/s3-configuration.md rename to docs/how-to/configure-s3.md index 12ab7761..2cfc61fc 100644 --- a/docs/Tutorial/s3-configuration.md +++ b/docs/how-to/configure-s3.md @@ -1,4 +1,4 @@ -# S3 configuration +# How to configure S3 An S3 bucket can be leveraged to serve the static resources packaged by Discourse, potentically improving performance. Moreover, it is required when scaling the charm to serve the uploaded files. To configure it to set the following configuration options with the appropriate values for your existing bucket `juju config [charm_name] [configuration]=[value]`: @@ -16,4 +16,4 @@ To enable S3 to perform backups, you'll need to specify also `s3_backup_bucket`. It is also possible to configure the S3 bucket to act as a content delivery network (CDN) serving the static content directly from the bucket, for that, set `s3_cdn_url`. If you wish to modify the CORS set up, you can do so by changing `s3_install_cors_rule`. -For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure). \ No newline at end of file +For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure). diff --git a/docs/Tutorial/saml-configuration.md b/docs/how-to/configure-saml.md similarity index 92% rename from docs/Tutorial/saml-configuration.md rename to docs/how-to/configure-saml.md index 04f595ef..3edee3bd 100644 --- a/docs/Tutorial/saml-configuration.md +++ b/docs/how-to/configure-saml.md @@ -1,8 +1,8 @@ -# SAML configuration +# How to configure SAML To configure Discourse's SAML integration you'll have to set the following configuration options with the appropriate values for your SAML server by running `juju config [charm_name] [configuration]=[value]`. The SAML URL needs to be scpecified in `saml_target_url`. If you wish to force the login to go through SAML, enable `force_saml_login`. The groups to be synced from the provider can be defined in `saml_sync_groups` as a comma-separated list of values. -For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure). \ No newline at end of file +For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure). diff --git a/docs/Tutorial/smtp-configuration.md b/docs/how-to/configure-smtp.md similarity index 94% rename from docs/Tutorial/smtp-configuration.md rename to docs/how-to/configure-smtp.md index 50d3c78e..8201fec2 100644 --- a/docs/Tutorial/smtp-configuration.md +++ b/docs/how-to/configure-smtp.md @@ -1,4 +1,4 @@ -# SMTP configuration +# How to configure SMTP To configure Discourse's SMTP you'll have to set the following configuration options with the appropriate values for your SMTP server by running `juju config [charm_name] [configuration]=[value]`. @@ -8,4 +8,4 @@ If authentication is needed, `smtp_authentication` will need to be set to the ap If needed, the verification of the SSL certs can be turned on and off with `smtp_openssl_verify_mode`. -For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure). \ No newline at end of file +For more details on the configuration options and their default values see the [configuration reference](https://charmhub.io/discourse-k8s/configure). diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md new file mode 100644 index 00000000..ecf30057 --- /dev/null +++ b/docs/how-to/contribute.md @@ -0,0 +1,104 @@ +# How to contribute + +## Overview + +This document explains the processes and practices recommended for contributing +enhancements to the Discourse operator. + +- Generally, before developing enhancements to this charm, you should consider +[opening an issue](https://github.com/canonical/discourse-k8s-operator/issues) +explaining your use case. +- If you would like to chat with us about your use-cases or proposed +implementation, you can reach us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev) +or [Discourse](https://discourse.charmhub.io/). +- Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) +library will help you a lot when working on new features or bug fixes. +- All enhancements require review before being merged. Code review typically +examines + - code quality + - test coverage + - user experience for Juju operators of this charm. +- Please help us out in ensuring easy to review branches by rebasing your pull +request branch onto the `main` branch. This also avoids merge commits and +creates a linear Git commit history. +- Please generate src documentation for every commit. See the section below for +more details. + +## Developing + +The code for this charm can be downloaded as follows: + +``` +git clone https://github.com/canonical/discourse-k8s-operator +``` + +You can use the environments created by `tox` for development: + +```shell +tox --notest -e unit +source .tox/unit/bin/activate +``` + +### Testing + +Note that the [Discourse](discourse_rock/rockcraft.yaml) image need to be built and +pushed to microk8s for the tests to run. It should +be tagged as `localhost:32000/discourse:latest` so that Kubernetes knows how to pull them +from the MicroK8s repository. Note that the MicroK8s registry needs to be +enabled using `microk8s enable registry`. More details regarding the OCI image +below. The following commands can then be used to run the tests: + +* `tox`: Runs all of the basic checks (`lint`, `unit`, `static`, and `coverage-report`). +* `tox -e fmt`: Runs formatting using `black` and `isort`. +* `tox -e lint`: Runs a range of static code analysis to check the code. +* `tox -e static`: Runs other checks such as `bandit` for security issues. +* `tox -e unit`: Runs the unit tests. +* `tox -e integration`: Runs the integration tests. + +### Generating src docs for every commit + +Run the following command: + +```bash +echo -e "tox -e src-docs\ngit add src-docs\n" >> .git/hooks/pre-commit +chmod +x .git/hooks/pre-commit +``` + +## Build charm + +Build the charm in this git repository using: + +```shell +charmcraft pack +``` +For the integration tests (and also to deploy the charm locally), the discourse +image is required in the microk8s registry. To enable it: + +```shell + microk8s enable registry +``` + +The following commands import the images in the Docker daemon and push them into +the registry: + +```shell + cd [project_dir]/discourse_rock && rockcraft pack rockcraft.yaml + skopeo --insecure-policy copy oci-archive:discourse_1.0_amd64.rock docker-daemon:localhost:32000/discourse:latest + docker push localhost:32000/discourse:latest +``` + +### Deploy + +```bash +# Create a model +juju add-model discourse-dev +# Enable DEBUG logging +juju model-config logging-config="=INFO;unit=DEBUG" +# Deploy the charm (assuming you're on amd64) +juju deploy ./discourse-k8s_ubuntu-20.04-amd64.charm \ + --resource discourse-image=localhost:32000/discourse:latest \ +``` + +## Canonical Contributor Agreement + +Canonical welcomes contributions to the Discourse Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution. diff --git a/docs/Tutorial/upgrades.md b/docs/how-to/upgrade.md similarity index 98% rename from docs/Tutorial/upgrades.md rename to docs/how-to/upgrade.md index 973861b5..a65ec8a0 100644 --- a/docs/Tutorial/upgrades.md +++ b/docs/how-to/upgrade.md @@ -1,8 +1,9 @@ -# Upgrades +# How to upgrade Upgrades are done just by running the `juju refresh` subcommand. Juju, Kubernetes, and Discourse then work together to ensure that one pod is upgraded to the new version and makes any database schema changes before the rest of the pods are upgraded in their turn. ## Upgrading from pod-spec to sidecar + It is recommended to take a database backup before starting an upgrade from pod-spec to the sidecar version of the discourse-k8s charm. When upgrading from the pod-spec charm some downtime is to be expected. The existing Deployment will be deleted and a new StatefulSet will be created from scratch. Hence, the charm will be unresponsive while the discourse image resource is downloaded from the Charmhub registry and the first unit is spun up. @@ -41,4 +42,4 @@ Given that the image is now packed and released as a charm resource, the followi * `image_user` * `image_pass` -You can use a different image than the one deployed by default with the charm using the [attach-resource](https://juju.is/docs/olm/juju-attach-resource) juju command. \ No newline at end of file +You can use a different image than the one deployed by default with the charm using the [attach-resource](https://juju.is/docs/olm/juju-attach-resource) juju command. diff --git a/docs/index.md b/docs/index.md index 7eaea2c0..3720f847 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,13 @@ -For more information on Redis and PostgreSQL relations see [this section](https://charmhub.io/discourse-k8s/docs/database-relations). +# Charmed Discourse k8s documentation -For details on configuration options, see [this page](https://charmhub.io/discourse-k8s/configure). +This charm simplifies initial deployment and "day N" operations of Discourse +on Kubernetes, such as scaling the number of instances, integration with SSO, +access to S3 for redundant file storage and more. It allows for deployment on +many different Kubernetes platforms, from [MicroK8s](https://microk8s.io) or +[Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes +offerings. + +Discourse is an open-source software application used to create customer-friendly and community-friendly discussion platforms, forums, and mailing lists. It's designed to work as a discussion platform for various topics and is widely used by numerous organizations and individuals to build communities, provide customer support, and facilitate conversations. The platform is built with a focus on simplicity, user-friendliness, and responsiveness, making it accessible from both desktops and mobile devices. Discourse provides various moderation and administration tools, enabling community managers to maintain a healthy and constructive environment. ## Contributing to this documentation @@ -8,6 +15,17 @@ Documentation is an important part of this project, and we take the same open-so If there's a particular area of documentation that you'd like to see that's missing, please [file a bug](https://github.com/canonical/discourse-k8s-operator/issues). +## Project and community + +The Discourse Operator is a member of the Ubuntu family. It's an open source +project that warmly welcomes community projects, contributions, suggestions, +fixes and constructive feedback. + +- [Code of conduct](https://ubuntu.com/community/code-of-conduct) +- [Get support](https://discourse.charmhub.io/) +- [Join our online chat](https://chat.charmhub.io/charmhub/channels/charm-dev) +- [Contribute](https://charmhub.io/discourse-k8s/docs/how-to-contribute) + ## In this documentation | | | diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md new file mode 100644 index 00000000..a1140ed9 --- /dev/null +++ b/docs/reference/integrations.md @@ -0,0 +1,66 @@ +# Integrations + +### db + +_Interface_: pgsql +_Supported charms_: [postgresql-k8s](https://charmhub.io/postgresql-k8s), +[postgresql](https://charmhub.io/postgresql) + +Database integration is a required relation for the Discourse charm to supply +structured data storage for Discourse. + +Database integrate command: `juju integrate discourse-k8s postgresql-k8s:db` + +### grafana-dashboard + +_Interface_: grafana-dashboard +_Supported charms_: [grafana-k8s](https://charmhub.io/grafana-k8s) + +Grafana-dashboard relation enables quick dashboard access already tailored to +fit the needs of operators to monitor the charm. The template for the Grafana +dashboard for Discourse charm can be found at `/src/grafana_dashboards/discourse.json`. +In Grafana UI, it can be found as “Discourse Operator” under the General section of the dashboard browser +(`/dashboards`). Modifications to the dashboard can be made but will not be +persisted upon restart/redeployment of the charm. + +Grafana-Prometheus integrate command: +``` +juju integrate grafana-k8s:grafana-source prometheus-k8s:grafana-source +``` +Grafana-dashboard integrate command: +``` +juju integrate discourse-k8s grafana-dashboard` +``` + +### ingress + +_Interface_: ingress +_Supported charms_: [nginx-ingress-integrator](https://charmhub.io/nginx-ingress-integrator), +[traefik](https://charmhub.io/traefik-k8s) + +Ingress manages external http/https access to services in a kubernetes cluster. +Note that the kubernetes cluster must already have an nginx ingress controller +already deployed. Documentation to enable ingress in MicroK8s can be found in +[Addon: Ingress](https://microk8s.io/docs/addon-ingress). + +Ingress integrate command: `juju integrate discourse-k8s nginx-ingress-integrator` + +### metrics-endpoint + +_Interface_: [prometheus_scrape](https://charmhub.io/interfaces/prometheus_scrape-v0) +_Supported charms_: [prometheus-k8s](https://charmhub.io/prometheus-k8s) + +Metrics-endpoint relation allows scraping the `/metrics` endpoint provided by Discourse. +The metrics are exposed in the [open metrics format](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#data-model) and will only be scraped by Prometheus once the +relation becomes active. For more information about the metrics exposed, refer to ["How to monitor Discourse metrics using Prometheus"](https://meta.discourse.org/t/discourse-prometheus/72666). + +Metrics-endpoint integrate command: `juju integrate discourse-k8s prometheus-k8s` + +### redis + +_Interface_: redis +_Supported charms_: [redis-k8s](https://charmhub.io/redis-k8s) + +Discourse uses Redis to run background tasks (with Sidekiq) and keep the application fast and responsive. It enables real-time updates on the pages and helps in managing data efficiently. Redis also helps Discourse in balancing loads by managing rate limits, making it a crucial part of its system. + +Redis integrate commands: `juju integrate discourse-k8s redis-k8s` diff --git a/docs/Tutorial/getting-started.md b/docs/tutorial/getting-started.md similarity index 100% rename from docs/Tutorial/getting-started.md rename to docs/tutorial/getting-started.md