chore(docs): Set up Charmhub docs and update tutorial.

charm/charmcraft.yaml

@@ -32,6 +32,15 @@ description: |
   into multiple environments for testing of changes, and supports scaling out for
   enterprise deployments.
 
+links:
+  website:
+    - https://charmhub.io/httprequest-lego-provider
+  source:
+    - https://github.com/canonical/httprequest-lego-provider
+  issues:
+    - https://github.com/canonical/httprequest-lego-provider/issues
+  documentation: https://discourse.charmhub.io/t/httprequest-lego-provider-documentation-overview/15783
+
 extensions:
   - django-framework
 
@@ -45,7 +54,7 @@ config:
     git-repo:
       type: string
       description: >
-        The repository URL where the DNS records are stored. The username has to be provided as in 
+        The repository URL where the DNS records are stored. The username has to be provided as in
         git+ssh://username@repository@branch, where the branch is optional.
     git-ssh-key:
       type: string

charm/docs/index.md

@@ -0,0 +1,58 @@
+# HTTPRequest Lego provider
+
+  A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators)
+  deploying and managing [HTTP request Lego provider](https://go-acme.github.io/lego/dns/httpreq/)
+  on Kubernetes. HTTP request Lego provider is a web application implementing the [DNS HTTP request
+  provider as defined by ACME](https://go-acme.github.io/lego/dns/httpreq/) to manage DNS records.
+
+  This charm simplifies initial deployment and operations of the HTTP request Lego
+  provider on Kubernetes, enabling the automation of DNS management. It allows for deployment
+  on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io) to
+  [Charmed Kubernetes](https://ubuntu.com/kubernetes) and public cloud Kubernetes offerings.
+
+  As such, the charm makes it easy for those looking to host their own ACME provider, and gives
+  them the freedom to deploy on the Kubernetes platform of their choice.
+
+  For DevOps or SRE teams this charm will make operating HTTP request Lego provider simple and
+  straightforward through Juju's clean interface. It will allow easy deployment
+  into multiple environments for testing of changes, and supports scaling out for
+  enterprise deployments.
+
+## In this documentation
+
+| | |
+|--|--|
+|  [Tutorials](https://discourse.charmhub.io/t/httprequest-lego-provider-docs-getting-started/15784)</br>  Get started - a hands-on introduction to using the HTTPRequest Lego provider for new users </br> |  [How-to guides](https://charmhub.io/httprequest-lego-provider/docs/authentication) </br> Step-by-step guides covering key operations and common tasks |
+| [Reference](https://charmhub.io/httprequest-lego-provider/actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/httprequest-lego-provider/docs/architecture) </br> Concepts - discussion and clarification of key topics  |
+
+## Contributing to this documentation
+
+Documentation is an important part of this project, and we take the same open-source approach to the documentation as the code. As such, we welcome community contributions, suggestions and constructive feedback on our documentation. Our documentation is hosted on the [Charmhub forum](https://discourse.charmhub.io/) to enable easy collaboration. Please use the "Help us improve this documentation" links on each documentation page to either directly change something you see that's wrong, or ask a question, or make a suggestion about a potential change via the comments section.
+
+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/httprequest-lego-provider/issues).
+
+## Project and community
+
+HTTPRequest Lego Provider is an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
+- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
+- [Get support](https://discourse.charmhub.io/tag/mattermost)
+- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+- Contribute and report bugs to [the HTTPRequest Lego Provider](https://github.com/canonical/httprequest-lego-provider/issues)
+
+# Navigation
+
+[details=Mapping table]
+
+| Level | Path | Navlink |
+| -- | -- | -- |
+| 1 | tutorial | [Tutorial]() |
+| 2 | tutorial-deploy-the-deploy-the-httprequest-lego-provider-charm-for-the-first-time | [ Deploy the Httprequest Lego Provider charm for the first time](/t/httprequest-lego-provider-docs-getting-started/15784) |
+| 1 | how-to| [How to]() |
+| 2 | manage-domains | [Manage Domains](/t/httprequest-lego-provider-docs-how-to-manage-domains/15786) |
+| 2 | manage-users | [Manage Users](/t/httprequest-lego-provider-docs-how-to-manage-users/15787) |
+| 1 | reference| [Reference]() |
+| 2 | reference-actions | [Actions](/t/httprequest-lego-provider-docs-actions/15788) |
+| 2 | reference-configurations | [Configurations](/t/httprequest-lego-provider-docs-configurations/15789) |
+| 2 | reference-integrations | [Integrations](/t/httprequest-lego-provider-docs-integrations/15790) |
+
+[/details]

charm/docs/reference/actions.md

@@ -1,3 +1,6 @@
 # Actions
 
 See [Actions](https://charmhub.io/httprequest-lego-provider/actions).
+
+
+> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)

charm/docs/reference/configurations.md

@@ -1,3 +1,6 @@
-# Integrations
+# Configurations
 
-See [Integrations](https://charmhub.io/httprequest-lego-provider/integrations).
+See [Configurations](https://charmhub.io/httprequest-lego-provider/configure).
+
+
+> Read more about configurations in the Juju docs: [Configuration](https://juju.is/docs/juju/configuration)

charm/docs/reference/integrations.md

@@ -1,3 +1,5 @@
-# Configurations
+# Integrations
 
-See [Configurations](https://charmhub.io/httprequest-lego-provider/configure).
+See [Integrations](https://charmhub.io/httprequest-lego-provider/integrations).
+
+> Read more about integrations in the Juju docs: [Integration](https://juju.is/docs/juju/integration)

charm/docs/tutorial/getting-started.md

@@ -7,13 +7,25 @@
 - Integrate with [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/#what-is-ingress) by using [NGINX Ingress Integrator](https://charmhub.io/nginx-ingress-integrator/).
 
 ## Requirements
-
-- Juju 3 installed.
-- Juju controller and model created.
+- 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 following this guide: [Set up / Tear down your test environment](https://juju.is/docs/juju/set-up--tear-down-your-test-environment)
+- NGINX Ingress Controller. If you're using [MicroK8s](https://microk8s.io/), this can be done by running the command `microk8s enable ingress`. For more details, see [Addon: Ingress](https://microk8s.io/docs/addon-ingress).
 
 For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/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 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:
+```
+multipass shell my-juju-vm
+```
+
 ### Set up the tutorial model
 To easily clean up the resources and to separate your workload from the contents of this tutorial, set up a new model with the following command.
 
@@ -27,7 +39,7 @@ The HTTPRequest Lego provider requires integration with [the PostgreSQL K8s char
 
 Deploy the charms:
 
-```bash
+```
 juju deploy nginx-ingress-integrator --channel=v2/edge
 juju trust nginx-ingress-integrator --scope=cluster
 juju deploy postgresql-k8s --channel 14/stable
@@ -37,57 +49,81 @@ juju deploy httprequest-lego-provider --channel=latest/edge
 
 To see the pod created by the charm, run `kubectl get pods -n httprequest-lego-provider-tutorial`. The output is similar to the following:
 
-```bash
+```
 NAME                             READY   STATUS    RESTARTS   AGE
 httprequest-lego-provider-0      2/2     Running   0          9m36s
 ```
 
 Run [`juju status`](https://juju.is/docs/olm/juju-status) to see the current status of the deployment. In the Unit list, you can see that the charm is waiting:
 
-```bash
+```
 httprequest-lego-provider/0*  waiting   idle   10.1.180.77         Config git-repo is required
 ```
 
 This means the required configurations have not been set yet.
 
 ### Configure the Httprequest Lego Provider charm
- Provide the configurations `git-repo` and `git-ssh-key` required by the charm:
+> NOTE: For tutorial you can fork this [repo](https://github.com/canonical/httprequest-lego-provider/tree/main) and use you own fork and ssh key.
+> If you fork the repo the `git-repo` will be in the form `git+ssh://[email protected]/<username>/httprequest-lego-provider.git@main`.
+Provide the configurations `git-repo` and `git-ssh-key` required by the charm:
 
- ```bash
+```
 juju config httprequest-lego-provider git-repo=git+ssh://username@host/repo@branch
 juju config httprequest-lego-provider git-ssh-key=**REDACTED**
 ```
 You can see the message has changed:
 
-```bash
+```
 httprequest-lego-provider/0*  waiting   idle   10.1.180.77         Waiting for database integrations
 ```
 
 ### Integrate the Httprequest Lego Provider charm
 For the charm to reach active status, integrate the charm with the PostgreSQL K8s charm and the NGINX Ingress Integrator charm:
 
-```bash
+```
 juju integrate httprequest-lego-provider postgresql-k8s
 juju integrate httprequest-lego-provider nginx-ingress-integrator
 ```
 
 Run `juju status` and wait until the Application status is `Active`:
 
-```bash
+```
 App                        Version  Status   Scale  Charm                      Channel      Rev  Address         Exposed  Message
 httprequest-lego-provider           active       1  httprequest-lego-provider  latest/edge   17  10.152.183.194  no
 ```
 
 In order to access the HTTP endpoints, you'll need configure a hostname and add it to Django's allow list and configure the path routes that will be accessible:
-```bash
+```
 juju config nginx-ingress-integrator service-hostname=lego.local
 juju config httprequest-lego-provider django-allowed-hosts=localhost,127.0.0.1,lego.local
 juju config nginx-ingress-integrator path-routes="/admin,/present,/cleanup"
 ```
 
+### Create a user and log in
+
+To create a user, use the `create-user` action:
+```
+juju run httprequest-lego-provider/0 create-user username=my_user
+```
+
+The command will return the password of the created user.
+If you are following the tutorial in your local machine, modify your `/etc/hosts` file so that it points to `127.0.0.1`:
+
+```
+echo 127.0.0.1 lego.local >> /etc/hosts
+```
+
+After that, visit `http://lego.local/present` to reach Httprequest Lego Provider, using the credentials returned from the `create-user` action to login.
+
 ### Clean up the environment
 Congratulations! You have successfully finished the httprequest-lego-provider tutorial. You can now remove the model environment that you've created using the following command.
 
 ```
 juju destroy-model --destroy-storage httprequest-lego-provider-tutorial
 ```
+
+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 lego.local` line from the `/etc/hosts` file.