Revert "[discourse-gatekeeper] Migrate charm docs (#267)" (#268)

yanksyoon · web-flow · commit cd6a258c664f · 2025-03-12T11:59:40.000+08:00
This reverts commit 7d3d0c2.
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,6 @@
+# Changelog
+
+### 2025-03-10
+
+- Add charm architecture diagram.
+- Add changelog for tracking user-relevant changes.
diff --git a/docs/explanation/charm-architecture.md b/docs/explanation/charm-architecture.md
@@ -200,4 +200,5 @@ CharmBase is the base class from which all Charms are formed, defined by [Ops](h
 
 > See more in the Juju docs: [Charm](https://canonical-juju.readthedocs-hosted.com/en/3.6/user/reference/charm/).
 
-The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them.
+The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them.
+
diff --git a/docs/how-to/configure-hostname.md b/docs/how-to/configure-hostname.md
@@ -42,4 +42,4 @@ Test the ingress by sending a GET request to the service with `Host` headers.
 
 ```
 curl -H "Host: <desired-hostname>" http://<nginx-ingress-integrator-service-ip>
-```
+```
diff --git a/docs/how-to/configure-initial-settings.md b/docs/how-to/configure-initial-settings.md
@@ -1,8 +1,7 @@
 # How to configure initial settings
 
-[note]
-This only works when setting up WordPress initially, before database relation setup. Changing the value afterwards has no effect.
-[/note]
+> **NOTE** This only works when setting up WordPress initially, before database relation setup. Changing the
+value afterwards has no effect.
 
 By providing configuration value for `initial_settings` at deployment, you can tweak a few
 WordPress settings. For detailed information on configurable parameters, please refer to the
@@ -23,4 +22,4 @@ WordPress(`http://<wordpress-unit-ip>/wp-admin/options-general.php`).
 
 You can also pass in the wordpress-k8s `configuration.yaml` file with the parameters above. See how
 to pass in a configuration file in the
-[juju documentation](https://juju.is/docs/olm/manage-applications#heading--configure-an-application-during-deployment).
+[juju documentation](https://juju.is/docs/olm/manage-applications#heading--configure-an-application-during-deployment).
diff --git a/docs/how-to/configure-object-storage.md b/docs/how-to/configure-object-storage.md
@@ -59,4 +59,4 @@ You can then configure wordpress-k8s charm using the yaml contents above.
 
 ```
 juju config wordpress-k8s wp_plugin_openstack-objectstorage_config="$(cat <path-to-yaml>)"
-```
+```
diff --git a/docs/how-to/enable-waf.md b/docs/how-to/enable-waf.md
@@ -14,10 +14,8 @@ juju relate wordpress-k8s nginx-ingress-integrator
 
 ### Enable Modsecurity 3.0 WAF
 
-[note]
-This feature is only available for
+> **NOTE** This feature is only available for
 [nginx-ingress-integrator](https://charmhub.io/nginx-ingress-integrator) charm.
-[/note]
 
 The modsecurity WAF is enabled by default.
 
@@ -49,4 +47,4 @@ Annotations:     nginx.ingress.kubernetes.io/enable-modsecurity: true
 Events:          <none>
 ```
 
-Note the `nginx.ingress.kubernetes.io/enable-modsecurity: true` annotation.
+Note the `nginx.ingress.kubernetes.io/enable-modsecurity: true` annotation.
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -0,0 +1,43 @@
+# How-to guides
+
+The following guides cover key processes and common tasks for managing
+and using the WordPress charm.
+
+## Initial setup
+* [Retrieve initial credentials]
+* [Configure initial settings]
+
+## Basic operations
+* [Configure hostname]
+* [Configure object storage]
+* [Install plugins]
+* [Install themes]
+* [Integrate with COS]
+
+## Security
+* [Enable antispam]
+* [Enable WAF]
+* [Rotate secrets]
+
+## Upgrade and redeployment 
+* [Upgrade WordPress charm]
+* [Redeploy]
+
+## Development
+* [Contribute]
+
+<!--Links-->
+
+[Retrieve initial credentials]: retrieve-initial-credentials.md
+[Configure initial settings]: configure-initial-settings.md
+[Integrate with COS]: integrate-with-cos.md
+[Configure hostname]: configure-hostname.md
+[Install plugins]: install-plugins.md
+[Install themes]: install-themes.md
+[Configure object storage]: configure-object-storage.md
+[Enable antispam]: enable-antispam.md
+[Enable WAF]: enable-waf.md
+[Rotate secrets]: rotate-secrets.md
+[Upgrade WordPress charm]: upgrade-wordpress-charm.md
+[Redeploy]: redeploy.md
+[Contribute]: contribute.md
diff --git a/docs/how-to/integrate-with-cos.md b/docs/how-to/integrate-with-cos.md
@@ -53,4 +53,4 @@ juju run grafana-k8s/0 get-admin-password
 
 You can now log into the Grafana dashboard by visiting `http://<grafana-unit-ip>:3000`. Navigate to
 `http://<grafana-unit-ip>:3000/dashboards` and access the WordPress dashboard named Wordpress Operator
-Overview.
+Overview.
diff --git a/docs/how-to/retrieve-initial-credentials.md b/docs/how-to/retrieve-initial-credentials.md
@@ -4,7 +4,7 @@ Run the following command to get the initial admin password that can be used to
 `http://<wordpress-unit-ip>/wp-login.php`.
 
 ```
-juju run wordpress-k8s/0 get-initial-password
+juju run wordpress-k8s/0 get-initial-password 
 ```
 
 The output of the action should look something similar to the following:
@@ -20,7 +20,5 @@ unit-wordpress-k8s-0:
 
 You can use the password to login to the admin account in `http://<wordpress-unit-ip>/wp-admin.php`.
 
-[note]
-If the `admin_password` value was passed in the `initial_settings` configuration, the
+> **NOTE** If the `admin_password` value was passed in the `initial_settings` configuration, the
 password from the action is invalid.
-[/note]
diff --git a/docs/how-to/rotate-secrets.md b/docs/how-to/rotate-secrets.md
@@ -6,4 +6,4 @@ To securely update all the WordPress secrets, run the following action.
 juju run wordpress-k8s/0 rotate-wordpress-secrets
 ```
 
-This action will force users to be logged out. All sessions and cookies will be invalidated.
+This action will force users to be logged out. All sessions and cookies will be invalidated.
diff --git a/docs/how-to/upgrade-wordpress-charm.md b/docs/how-to/upgrade-wordpress-charm.md
@@ -17,4 +17,4 @@ After upgrading the WordPress Charm you need to update the database schema.
 
 ```
 juju run wordpress-k8s/0 update-database
-```
+```
diff --git a/docs/index.md b/docs/index.md
@@ -1,16 +1,16 @@
-A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing WordPress on Kubernetes. [WordPress](https://wordpress.com/) is the world's most popular website builder, and it's free and open-source.
+# Wordpress Operator
 
-This charm simplifies initial deployment and "day N" operations of WordPress on Kubernetes, including scaling the number of instances, integration with SSO, access to OpenStack Swift object storage for redundant file storage, and more. It allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes offerings.
+A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing WordPress on Kubernetes. [WordPress](https://wordpress.com/) is the world's most popular website builder, and it's free and open-source.
 
-As such, the charm makes it easy for those looking to take control of their own content management system whilst keeping operations simple and gives them the freedom to deploy on the Kubernetes platform of their choice.
+This charm simplifies initial deployment and operations of WordPress on Kubernetes, including scaling the number of instances, integration with SSO, access to OpenStack Swift object storage for redundant file storage, and more. It allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes offerings.
 
 This charm will make operating WordPress simple and straightforward for DevOps or SRE teams through Juju's clean interface. It will allow easy deployment into multiple environments to test changes and support scaling out for enterprise deployments.
 
 ## In this documentation
 
 | | |
 |--|--|
-|  [Tutorials](https://charmhub.io/wordpress-k8s/docs/tutorials-getting-started)</br>  Get started - a hands-on introduction to using the Charmed WordPress operator for new users </br> |  [How-to guides](https://charmhub.io/wordpress-k8s/docs/how-to) </br> Step-by-step guides covering key operations and common tasks |
+|  [Tutorials](https://charmhub.io/wordpress-k8s/docs/tutorials-getting-started)</br>  Get started - a hands-on introduction to using the Charmed WordPress operator for new users </br> |  [How-to guides](https://charmhub.io/wordpress-k8s/docs/how-to-contribute) </br> Step-by-step guides covering key operations and common tasks |
 | [Reference](https://charmhub.io/wordpress-k8s/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/wordpress-k8s/docs/explanation-overview) </br> Concepts - discussion and clarification of key topics  |
 
 ## Contributing to this documentation
@@ -25,10 +25,10 @@ The WordPress Operator is a member of the Ubuntu family. It's an open-source pro
 
 - [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](Contribute)
+- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+- [Contribute](https://github.com/canonical/wordpress-k8s-operator/blob/main/CONTRIBUTING.md)
 
-Thinking about using the WordPress Operator for your next project? [Get in touch](https://chat.charmhub.io/charmhub/channels/charm-dev)!
+Thinking about using the WordPress Operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
 
 # Contents
 
@@ -40,9 +40,9 @@ Thinking about using the WordPress Operator for your next project? [Get in touch
   1. [Configure object storage](how-to/configure-object-storage.md)
   1. [Install plugins](how-to/install-plugins.md)
   1. [Install themes](how-to/install-themes.md)
-  1. [Integrate with COS](how-to/integrate-with-cos.md)
+  1. [Integrate with COS](how-to/integrate-with-cos.md) 
   1. [Enable antispam](how-to/enable-antispam.md)
-  1. [Enable WAF](how-to/enable-waf.md)
+  1. [Enable WAF](how-to/enable-waf.md)  
   1. [Rotate secrets](how-to/rotate-secrets.md)
   1. [Upgrade WordPress charm](how-to/upgrade-wordpress-charm.md)
   1. [Redeploy](how-to/redeploy.md)
@@ -54,4 +54,4 @@ Thinking about using the WordPress Operator for your next project? [Get in touch
   1. [Plugins](reference/plugins.md)
   1. [Themes](reference/themes.md)
 1. [Explanation](explanation)
-  1. [Charm architecture](explanation/architecture.md)
+  1. [Charm architecture](explanation/charm-architecture.md)
diff --git a/docs/reference/actions.md b/docs/reference/actions.md
@@ -2,6 +2,4 @@
 
 See [Actions](https://charmhub.io/wordpress-k8s/actions).
 
-[note]
-Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)
-[/note]
+> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)
diff --git a/docs/reference/configurations.md b/docs/reference/configurations.md
@@ -2,6 +2,4 @@
 
 See [Configurations](https://charmhub.io/wordpress-k8s/configure).
 
-[note]
-Read more about configurations in the Juju docs: [Configuration](https://juju.is/docs/juju/configuration)
-[/note]
+> Read more about configurations in the Juju docs: [Configuration](https://juju.is/docs/juju/configuration)
diff --git a/docs/reference/external-access.md b/docs/reference/external-access.md
@@ -0,0 +1,23 @@
+# External Access Requirements
+
+The WordPress charm may need to connect to external services and resources for
+certain functionalities.
+
+## OpenStack Object Storage
+
+When activated, the WordPress instance will need to connect to configured
+OpenStack object storage for uploading and retrieval of media and assets.
+
+## Akismet Spam Protection Plugin
+
+The Akismet spam protection plugin, when enabled via the `wp_plugin_akismet_key`
+configuration, requires internet access to connect with
+the [Akismet API server](https://akismet.com/support/general/connection-issues/).
+This connection is essential for verifying and managing spam content.
+
+## Installing Additional Plugins or Themes
+
+For the installation of additional plugins or themes, the WordPress instance
+must access the main WordPress site to download installation files. Some plugins
+or themes might also need internet access to operate correctly after they are
+installed.
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
@@ -78,4 +78,4 @@ in the database side.
 Example database integrate command: 
 ```
 juju integrate wordpress-k8s:database mysql-k8s:database
-```
+```
diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md
@@ -80,4 +80,4 @@ _\*The descriptions of the following plugins are taken from the WordPress plugin
 - [wp-statistics](https://wordpress.org/plugins/wp-statistics/): GDPR compliant website statistics
   tool.
 - [xubuntu-team-members](https://git.launchpad.net/~canonical-sysadmins/wordpress/+git/wp-plugin-xubuntu-team-members):
-  Adds the role "Xubuntu Team member"
+  Adds the role "Xubuntu Team member"
diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -17,9 +17,7 @@ tutorial will walk you through each step of deployment to get a basic WordPress
 For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
 
 ### Shell into the Multipass VM
-[note]
-If you're working locally, you don't need to do this step.
-[/note]
+> NOTE: If you're working locally, you don't need to do this step.
 
 To be able to work inside the Multipass VM first you need to log in with the following command:
 ```bash
@@ -99,19 +97,18 @@ password: <password> # should look something like: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
 ```
 
-[note]
- If you are using Multipass VM for this tutorial, you will need to route the IP from Multipass. To do this first get the IP of the Multipass VM.
- Outside the Multipass VM run:
- ```
- multipass info my-juju-vm
- ```
- The IP you see here will be called <VM_IP> in this example.
+> NOTE: If you are using Multipass VM for this tutorial, you will need to route the IP from Multipass. To do this first get the IP of the Multipass VM.
+> Outside the Multipass VM run:
+> ```
+> multipass info my-juju-vm
+> ```
+> The IP you see here will be called <VM_IP> in this example.
+>
+> Then route:
+> ```
+> sudo ip route add <UNIT_IP> via <VM_IP>
+> ```
 
- Then route:
- ```
- sudo ip route add <UNIT_IP> via <VM_IP>
- ```
-[/note]
 
 You can now access your WordPress application at `http://<UNIT_IP>/wp-login.php` and log in with the admin username and password from the previous action.
 
@@ -129,4 +126,4 @@ If you used Multipass, to remove the Multipass instance you created for this tut
 
 ```
 multipass delete --purge my-juju-vm
-```
+```

-Original file line number
+Diff line change
 ```
 curl -H "Host: <desired-hostname>" http://<nginx-ingress-integrator-service-ip>
 -```
 +```