docs: basic charm docs (#13)

* docs: introduction

* docs: tutorial

* docs: reference

* docs: how-to

* docs: how-to get admin password

* docs: explanation deprecated relation

* chore: add charm artifact to gitignore

* chore: update configurations ref link

* docs: add cmr docs

* docs: remove docs for upload-charm-docs

* docs: improve configure update time range explanation

* docs: initial overview page

* docs: add contents table

* docs: rephrase deprecated relation

* docs: add update-time-range detail

* fix: auto format

* docs: add detail to getting started

* docs: add how-to guide on cmr

* docs: fix typo

.gitignore

@@ -130,3 +130,6 @@ dmypy.json
 
 # rocks
 */*.rock
+
+# charm artifact
+*.charm

docs/explanation/agent-deprecated-relation.md

@@ -0,0 +1,6 @@
+# Agent-deprecated relation
+
+The agent-deprecated relation is a remains of the jenkins-k8s charm to provide backwards
+compatibility with the existing [jenkins charm](https://charmhub.io/jenkins). The deprecated
+relation should not be used as it provides an unstable relation implementation that could result in
+some agents not registering successfully.

docs/how-to/configure-update-time-range.md

@@ -0,0 +1,45 @@
+# How to configure update-time-range
+
+### Configure update-time-range
+
+Use the `update-time-range` configuration to set the time interval when `jenkins-k8s` automatically
+applies the latest patches for the current [LTS](https://www.jenkins.io/download/lts/) version.
+The minimum time interval is 1 hour. Time range is applied each day of the week.
+
+```
+juju config jenkins-k8s update-time-range=<desired-time-range>
+
+# desired-time-range example: 22-03 to allow patching from 10PM-03AM UTC.
+```
+
+Assuming the installed Jenkins LTS version to be 2.387, the output of `juju status` should look
+similar to the following before the update:
+
+```
+Model               Controller          Cloud/Region        Version  SLA          Timestamp
+jenkins-tutorial    microk8s-localhost  microk8s/localhost  2.9.43   unsupported  <timestamp>
+
+App                Version  Status      Scale  Charm              Channel      Rev  Address         Exposed  Message
+jenkins-k8s        2.387  active          1  jenkins-k8s        latest/edge     0   <ip-address>    no
+
+Unit            Workload  Agent  Address       Ports  Message
+jenkins-k8s/0*  active    idle   <ip-address>
+```
+
+After the update:
+
+```
+Model               Controller          Cloud/Region        Version  SLA          Timestamp
+jenkins-tutorial    microk8s-localhost  microk8s/localhost  2.9.43   unsupported  <timestamp>
+
+App                Version  Status      Scale  Charm              Channel      Rev  Address         Exposed  Message
+jenkins-k8s        2.387.3  active          1  jenkins-k8s        latest/edge  0    <ip-address>    no
+
+Unit            Workload  Agent  Address       Ports  Message
+jenkins-k8s/0*  active    idle   <ip-address>
+```
+
+Note the difference in patch version under the `Version` column of the application status.
+
+You can verify that the patch has been applied by signing into the Jenkins UI and checking the
+version number at the bottom right corner of the footer.

docs/how-to/get-admin-password.md

@@ -0,0 +1,27 @@
+# How to get admin password
+
+### Get admin password
+
+To retrieve the password for the admin account, you can run the `get-admin-password` action.
+
+```
+juju run-action jenkins-k8s/0 get-admin-password --wait
+```
+
+The output should look something similar to the contents below:
+
+```
+unit-jenkins-k8s-0:
+  UnitId: jenkins-k8s/0
+  id: "2"
+  results:
+    password: <password>
+  status: completed
+  timing:
+    completed: <timestamp>
+    enqueued: <timestamp>
+    started: <timestamp>
+```
+
+You can use the password retrieved above to access your Jenkins server UI at
+`http://<UNIT_IP>:8080` as the "admin" user.

docs/how-to/integrate-with-machine-agents.md

@@ -0,0 +1,54 @@
+# How to integrate with machine agents
+
+### Prerequisites
+
+This guide assumes the `jenkins-k8s` charm to already be deployed on a k8s juju model `tutorial`.
+
+To integrate machine (VM) agents, you'll need to have a bootstrapped machine model. Learn about
+bootstrapping different clouds
+[here](https://juju.is/docs/olm/get-started-with-juju#heading--prepare-your-cloud).
+
+Use `juju bootstrap localhost localhost` to bootstrap a `lxd` machine controller with the name
+`localhost` for tutorial purposes.
+
+Use `juju add-model tutorial` to add a model named `tutorial`.
+
+### Deploy Jenkins agents (VM)
+
+Deploy 3 units of [jenkins agents](https://charmhub.io/jenkins-agent) on the lxd cloud.
+
+```
+# Deploy an edge version of the charm until stable version is released.
+juju deploy jenkins-agent --channel=latest/edge -n3
+```
+
+### Create an offer for Cross Model Relation
+
+To relate charms
+[across different models](https://juju.is/docs/juju/manage-cross-model-integrations), a juju
+[`offer`](https://juju.is/docs/juju/manage-cross-model-integrations#heading--create-an-offer) is
+required.
+
+Create an offer of the `jenkins-agent` charm's `agent` relation.
+
+```
+juju offer jenkins-agent:agent
+```
+
+The output should look similar to the contents below:
+
+```
+Application "jenkins-agent" endpoints [agent] available at "admin/tutorial.jenkins-agent"
+```
+
+### Relate Jenkins agents through the offer
+
+Switch back to the k8s model where `jenkins-k8s` charm is deployed. An example of the switch
+command looks like the following: `juju switch microk8s-localhost:tutorial`.
+
+Relate the agents to the `jenkins-k8s` server charm through the offer.
+The syntax of the offer is as follows: `<controller>:<user>/<model>.<charm>`.
+
+```
+juju relate jenkins-k8s:agent localhost:admin/tutorial.jenkins-agent
+```

docs/index.md

@@ -0,0 +1,34 @@
+# Jenkins-k8s Operator
+
+A Juju charm deploying and managing Jenkins on Kubernetes. [Jenkins](https://www.jenkins.io/) is an open source automation server. Jenkins provides hundreds of plugins to support building, deploying and automating any project. It can be integrated with both k8s and machine (VM) agents for use.
+
+This charm simplifies initial deployment and "day N" operations of Jenkins on Kubernetes, including integration with Jenkins agent instances, automatic patch updates 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.
+
+As such, the charm makes it easy for those looking to take control of their own automation management system whilst keeping operations simple, and gives them the freedom to deploy on the Kubernetes platform of their choice.
+
+For DevOps or SRE teams this charm will make operating Jenkins simple and straightforward through Juju's clean interface. It will allow easy deployment into multiple environments for testing of changes, and supports scaling out agents for enterprise deployments.
+
+## Project and community
+
+The Jenkins-k8s 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](Contribute)
+
+Thinking about using the Jenkins-k8s Operator for your next project? [Get in touch](https://chat.charmhub.io/charmhub/channels/charm-dev)!
+
+# Contents
+
+1. [Tutorial](tutorial)
+   1. [Getting Started](tutorial/getting-started.md)
+1. [How to](how-to)
+   1. [Configure update-time-range](how-to/configure-update-time-range.md)
+   1. [Get admin password](how-to/get-admin-password.md)
+1. [Reference](reference)
+   1. [Actions](reference/actions.md)
+   1. [Configurations](reference/configurations.md)
+   1. [Integrations](reference/integrations.md)
+1. [Explanation](explanation)
+   1. [Agent-deprecated relation](explanation/agent-deprecated-relation.md)

docs/reference/actions.md

@@ -0,0 +1,3 @@
+# Actions
+
+See [Actions](https://charmhub.io/jenkins-k8s/actions).

docs/reference/configurations.md

@@ -0,0 +1,3 @@
+# Configurations
+
+See [Configure](https://charmhub.io/jenkins-k8s/configure).

docs/reference/integrations.md

@@ -0,0 +1,27 @@
+# Integrations
+
+### agent
+
+_Interface_: jenkins_agent_v0  
+_Supported charms_: [jenkins-agent-k8s](https://charmhub.io/jenkins-agent-k8s),
+[jenkins-agent](https://charmhub.io/jenkins-agent)
+
+Jenkins agents provide a way to perform tasks scheduled by the Jenkins server. Jenkins agents are
+used to distribute workload across multiple containers, allowing parallel execution of jobs.
+
+Example agent relate command: `juju relate jenkins-k8s:agent jenkins-agent-k8s:agent`
+
+To create a [cross model relation](https://juju.is/docs/olm/manage-cross-model-integrations) with
+a jenkins-agent (VM) charm, create an offer from the machine model.
+
+`juju offer jenkins-agent:agent`
+
+Then, relate the offer from the k8s model where jenkins-k8s charm resides.
+
+`juju relate jenkins-k8s:agent <controller-name>:<juju-user>/<agent-model>.jenkins-agent`
+
+An example of such command would look like the following, using a jenkins-agent deployed on a
+localhost
+[lxd controller](https://juju.is/docs/olm/get-started-with-juju#heading--prepare-your-cloud).
+
+`juju relate jenkins-k8s:agent localhost:admin/jenkins-vm-model.jenkins-agent`

docs/tutorial/getting-started.md

@@ -0,0 +1,95 @@
+# Getting Started
+
+## What you'll do
+
+- Deploy the [jenkins-k8s charm](https://charmhub.io/jenkins-k8s)
+- [Deploy and integrate agents](#deploy-and-relate-agents)
+- [Get admin password](#get-admin-password)
+
+The jenkins-k8s charm helps deploy a Jenkins automation server application with ease and
+also helps operate the charm. This
+tutorial will walk you through each step of deployment to get a basic Jenkins server deployment.
+
+### Prerequisites
+
+To deploy jenkins-k8s charm, you will need a juju bootstrapped with any kubernetes controller.
+To see how to bootstrap your juju installation with microk8s, please refer to the documentation
+on microk8s [installation](https://juju.is/docs/olm/microk8s).
+
+### Setting up the tutorial model
+
+To easily clean up the resources and to separate your workload from the contents of this tutorial,
+it is recommended to set up a new model with the following command.
+
+```
+juju add-model jenkins-tutorial
+```
+
+### Deploy the jenkins-k8s charm
+
+Start off by deploying the jenkins-k8s charm. By default it will deploy the latest stable release
+of the jenkins-k8s charm.
+
+```
+# Deploy an edge version of the charm until stable version is released.
+juju deploy jenkins-k8s --channel=latest/edge
+```
+
+The Jenkins application can only have a single server unit. Adding more units through `--num-units`
+parameter will cause the application to misbehave.
+
+### Deploy and integrate agents
+
+By default, jenkins-k8s server application is installed with 0 executors for security purposes.
+A functional Jenkins application requires additional Jenkins agents to be integrated.
+
+The following commands deploy 3 units of the jenkins-agent-k8s charm and integrate them with the
+jenkins-k8s charm.
+
+```
+juju deploy jenkins-agent-k8s --channel=latest/edge --num-units=3
+
+# 'agent' relation name is required since jenkins-k8s charm provides multiple compatible
+# interfaces with jenkins-agent-k8s charm.
+juju relate jenkins-k8s:agent jenkins-agent-k8s:agent
+```
+
+### Get admin credentials
+
+You can access the Jenkins server application UI by accessing the IP of a jenkins-k8s unit. To
+start managing Jenkins server as an administrator, you need to get the password for the admin
+account.
+
+By running the `get-admin-password` action on a jenkins-k8s unit, juju will read and fetch the
+admin credentials setup for you. You can use the following command below.
+
+```
+juju run-action jenkins-k8s/0 get-admin-password --wait
+```
+
+The output should look something similar to the contents below:
+
+```
+unit-jenkins-k8s-0:
+  UnitId: jenkins-k8s/0
+  id: "2"
+  results:
+    password: <password>
+  status: completed
+  timing:
+    completed: <timestamp>
+    enqueued: <timestamp>
+    started: <timestamp>
+```
+
+You can now access your Jenkins server UI at `http://<UNIT_IP>:8080` and login using username
+"admin" and password from the action above.
+
+### Cleaning up the environment
+
+Congratulations! You have successfully finished the jennkins-k8s tutorial. You can now remove the
+model environment that you’ve created using the following command.
+
+```
+juju destroy model jenkins-tutorial -y --release-storage
+```

metadata.yaml

@@ -24,7 +24,7 @@ description: |
   For DevOps and SRE teams, this charm will make operating Jenkins simple and straightforward
   through Juju's clean interface. Allowing both kubernetes and machine agent relations, it supports
   multiple environments for automation.
-docs: ""
+docs: https://discourse.charmhub.io/t/jenkins-k8s-documentation-overview/11169
 issues: https://github.com/canonical/jenkins-k8s-operator/issues
 source: https://github.com/canonical/jenkins-k8s-operator
 tags: