From b6c0399debbf977e5f2036b79986fe97ddb0d17a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 5 Dec 2023 02:44:49 +0000
Subject: [PATCH 1/9] modified:
 docs/reference/configurations.md,docs/how-to/configure-restart-time-range.md,docs/how-to/get-admin-password.md,docs/how-to/integrate-with-machine-agents.md,docs/index.md,docs/reference/integrations.md,docs/explanation/agent-deprecated-relation.md,docs/tutorial/getting-started.md,docs/reference/actions.md
 // removed:
 docs/how-to/configure-installable-plugins.md,docs/how-to/rotate-credentials.md

---
 docs/explanation/agent-deprecated-relation.md |  2 +-
 docs/how-to/configure-installable-plugins.md  | 22 ---------------
 ...ange.md => configure-update-time-range.md} | 17 ++++-------
 docs/how-to/get-admin-password.md             |  2 +-
 docs/how-to/integrate-with-machine-agents.md  |  2 +-
 docs/how-to/rotate-credentials.md             | 28 -------------------
 docs/index.md                                 | 16 +++++------
 docs/reference/actions.md                     |  2 +-
 docs/reference/configurations.md              |  2 +-
 docs/reference/integrations.md                |  2 +-
 docs/tutorial/getting-started.md              |  2 +-
 11 files changed, 21 insertions(+), 76 deletions(-)
 delete mode 100644 docs/how-to/configure-installable-plugins.md
 rename docs/how-to/{configure-restart-time-range.md => configure-update-time-range.md} (75%)
 delete mode 100644 docs/how-to/rotate-credentials.md

diff --git a/docs/explanation/agent-deprecated-relation.md b/docs/explanation/agent-deprecated-relation.md
index 7d2db782..1a07b63c 100644
--- a/docs/explanation/agent-deprecated-relation.md
+++ b/docs/explanation/agent-deprecated-relation.md
@@ -3,4 +3,4 @@
 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.
+some agents not registering successfully.
\ No newline at end of file
diff --git a/docs/how-to/configure-installable-plugins.md b/docs/how-to/configure-installable-plugins.md
deleted file mode 100644
index d96f024d..00000000
--- a/docs/how-to/configure-installable-plugins.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# How to configure installable plugins
-
-### Configure `plugins`
-
-Use the `plugins` configuration to allow a list of plugins to be installed on Jenkins.
-Comma-separated list of allowed plugin short names. If empty, any plugin can be installed.
-Plugins installed by the user and their dependencies will be removed automatically if not on
-the list. Included plugins are not automatically installed.
-The plugins are cleaned up at `update-status` hook trigger. If the `restart-time-range`
-configuration option is provided, the plugins are cleaned up during the defined time range.
-
-On trigger it will:
-
-1. Delete any installed plugins not defined on the list and their dependencies.
-2. Set a system message on Jenkins indicating which user installed plugins have been deleted.
-
-```
-juju config jenkins-k8s plugins=<allowed-plugins-csv>
-
-# plugins example: `git, azure-cli, aws-credentials` will allow git, azure and aws-credentials
-plugins to be installed.
-```
diff --git a/docs/how-to/configure-restart-time-range.md b/docs/how-to/configure-update-time-range.md
similarity index 75%
rename from docs/how-to/configure-restart-time-range.md
rename to docs/how-to/configure-update-time-range.md
index 40201859..aa62a388 100644
--- a/docs/how-to/configure-restart-time-range.md
+++ b/docs/how-to/configure-update-time-range.md
@@ -1,18 +1,13 @@
-# How to configure restart-time-range
+# How to configure update-time-range
 
-### Configure restart-time-range
-
-Use the `restart-time-range` configuration to set the time interval when `jenkins-k8s`
-
-1. automatically applies the latest patches for the current
-   [LTS](https://www.jenkins.io/download/lts/) version.
-2. automatically remove plugins that are installed on the system but are not part of the `plugins`
-   configuration option.
+### 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 restart-time-range=<desired-time-range>
+juju config jenkins-k8s update-time-range=<desired-time-range>
 
 # desired-time-range example: 22-03 to allow patching from 10PM-03AM UTC.
 ```
@@ -47,4 +42,4 @@ 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.
+version number at the bottom right corner of the footer.
\ No newline at end of file
diff --git a/docs/how-to/get-admin-password.md b/docs/how-to/get-admin-password.md
index 5d571419..fd0f86c4 100644
--- a/docs/how-to/get-admin-password.md
+++ b/docs/how-to/get-admin-password.md
@@ -24,4 +24,4 @@ unit-jenkins-k8s-0:
 ```
 
 You can use the password retrieved above to access your Jenkins server UI at
-`http://<UNIT_IP>:8080` as the "admin" user.
+`http://<UNIT_IP>:8080` as the "admin" user.
\ No newline at end of file
diff --git a/docs/how-to/integrate-with-machine-agents.md b/docs/how-to/integrate-with-machine-agents.md
index 9090cf26..08af2665 100644
--- a/docs/how-to/integrate-with-machine-agents.md
+++ b/docs/how-to/integrate-with-machine-agents.md
@@ -51,4 +51,4 @@ The syntax of the offer is as follows: `<controller>:<user>/<model>.<charm>`.
 
 ```
 juju relate jenkins-k8s:agent localhost:admin/tutorial.jenkins-agent
-```
+```
\ No newline at end of file
diff --git a/docs/how-to/rotate-credentials.md b/docs/how-to/rotate-credentials.md
deleted file mode 100644
index d1dbb6c4..00000000
--- a/docs/how-to/rotate-credentials.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# How to rotate credentials
-
-### Rotate credentials
-
-To rotate credentials for the admin account and invalidate all logged in user sessions, run the
-`rotate-credentials` action.
-
-```
-juju run-action jenkins-k8s/0 rotate-credentials --wait
-```
-
-The output should look similar to the contents below:
-
-```
-unit-jenkins-k8s-0:
-  UnitId: jenkins-k8s/0
-  id: "1"
-  results:
-    password: <password>
-  status: completed
-  timing:
-    completed: <timestamp>
-    enqueued: <timestamp>
-    started: <timestamp>
-```
-
-You can use the newly generated password above to access your Jenkins server UI at
-`http://<UNIT_IP>:8080` as the "admin" user.
diff --git a/docs/index.md b/docs/index.md
index e4dfa481..dd1bd66c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -22,14 +22,14 @@ Thinking about using the Jenkins-k8s Operator for your next project? [Get in tou
 # Contents
 
 1. [Tutorial](tutorial)
-   1. [Getting Started](tutorial/getting-started.md)
+  1. [Getting Started](tutorial/getting-started.md)
 1. [How to](how-to)
-   1. [Configure restart-time-range](how-to/configure-restart-time-range.md)
-   1. [Get admin password](how-to/get-admin-password.md)
-   1. [Rotate credentials](how-to/rotate-credentials.md)
+  1. [Configure update-time-range](how-to/configure-update-time-range.md)
+  1. [Get admin password](how-to/get-admin-password.md)
+  1. [How to integrate with machine agents](how-to/integrate-with-machine-agents.md)
 1. [Reference](reference)
-   1. [Actions](reference/actions.md)
-   1. [Configurations](reference/configurations.md)
-   1. [Integrations](reference/integrations.md)
+  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)
+  1. [Agent-deprecated relation](explanation/agent-deprecated-relation.md)
\ No newline at end of file
diff --git a/docs/reference/actions.md b/docs/reference/actions.md
index 3c9809e4..8cb2adbf 100644
--- a/docs/reference/actions.md
+++ b/docs/reference/actions.md
@@ -1,3 +1,3 @@
 # Actions
 
-See [Actions](https://charmhub.io/jenkins-k8s/actions).
+See [Actions](https://charmhub.io/jenkins-k8s/actions).
\ No newline at end of file
diff --git a/docs/reference/configurations.md b/docs/reference/configurations.md
index b5655b26..8d84fbe4 100644
--- a/docs/reference/configurations.md
+++ b/docs/reference/configurations.md
@@ -1,3 +1,3 @@
 # Configurations
 
-See [Configure](https://charmhub.io/jenkins-k8s/configure).
+See [Configure](https://charmhub.io/jenkins-k8s/configure).
\ No newline at end of file
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
index 156b2e93..998d25f7 100644
--- a/docs/reference/integrations.md
+++ b/docs/reference/integrations.md
@@ -66,4 +66,4 @@ Performance and Health Overview” under the General section of the dashboard br
 restart/redeployment of the charm.
 
 Grafana-Prometheus relate command: `juju relate grafana-k8s:grafana-source prometheus-k8s:grafana-source`
-Grafana-dashboard relate command: `juju relate jenkins-k8s:grafana-dashboard grafana-k8s:grafana-dashboard`
+Grafana-dashboard relate command: `juju relate jenkins-k8s:grafana-dashboard grafana-k8s:grafana-dashboard`
\ No newline at end of file
diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md
index c0f4be0d..9d0ebc2a 100644
--- a/docs/tutorial/getting-started.md
+++ b/docs/tutorial/getting-started.md
@@ -92,4 +92,4 @@ model environment that you’ve created using the following command.
 
 ```
 juju destroy model jenkins-tutorial -y --release-storage
-```
+```
\ No newline at end of file

From 1ec782563b8f34015b2e2aa15cd9ad194ad522cc Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Wed, 6 Dec 2023 02:36:15 +0000
Subject: [PATCH 2/9] modified: docs/index.md // new:
 docs/how-to/rotate-credentials.md,docs/how-to/configure-installable-plugins.md

---
 docs/how-to/configure-installable-plugins.md | 22 +++++++++++++++
 docs/how-to/rotate-credentials.md            | 28 ++++++++++++++++++++
 docs/index.md                                |  4 ++-
 3 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 docs/how-to/configure-installable-plugins.md
 create mode 100644 docs/how-to/rotate-credentials.md

diff --git a/docs/how-to/configure-installable-plugins.md b/docs/how-to/configure-installable-plugins.md
new file mode 100644
index 00000000..8b0df51e
--- /dev/null
+++ b/docs/how-to/configure-installable-plugins.md
@@ -0,0 +1,22 @@
+# How to configure installable plugins
+
+### Configure `plugins`
+
+Use the `plugins` configuration to allow a list of plugins to be installed on Jenkins.
+Comma-separated list of allowed plugin short names. If empty, any plugin can be installed.
+Plugins installed by the user and their dependencies will be removed automatically if not on
+the list. Included plugins are not automatically installed.
+The plugins are cleaned up at `update-status` hook trigger. If the `restart-time-range`
+configuration option is provided, the plugins are cleaned up during the defined time range.
+
+On trigger it will:
+
+1. Delete any installed plugins not defined on the list and their dependencies.
+2. Set a system message on Jenkins indicating which user installed plugins have been deleted.
+
+```
+juju config jenkins-k8s plugins=<allowed-plugins-csv>
+
+# plugins example: `git, azure-cli, aws-credentials` will allow git, azure and aws-credentials
+plugins to be installed.
+```
\ No newline at end of file
diff --git a/docs/how-to/rotate-credentials.md b/docs/how-to/rotate-credentials.md
new file mode 100644
index 00000000..0e45b637
--- /dev/null
+++ b/docs/how-to/rotate-credentials.md
@@ -0,0 +1,28 @@
+# How to rotate credentials
+
+### Rotate credentials
+
+To rotate credentials for the admin account and invalidate all logged in user sessions, run the
+`rotate-credentials` action.
+
+```
+juju run-action jenkins-k8s/0 rotate-credentials --wait
+```
+
+The output should look similar to the contents below:
+
+```
+unit-jenkins-k8s-0:
+  UnitId: jenkins-k8s/0
+  id: "1"
+  results:
+    password: <password>
+  status: completed
+  timing:
+    completed: <timestamp>
+    enqueued: <timestamp>
+    started: <timestamp>
+```
+
+You can use the newly generated password above to access your Jenkins server UI at
+`http://<UNIT_IP>:8080` as the "admin" user.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index dd1bd66c..62a19385 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -24,9 +24,11 @@ Thinking about using the Jenkins-k8s Operator for your next project? [Get in tou
 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. [Configure restart-time-range](how-to/configure-restart-time-range.md)
+  1. [How to configure installable plugins](how-to/configure-installable-plugins.md)
   1. [Get admin password](how-to/get-admin-password.md)
   1. [How to integrate with machine agents](how-to/integrate-with-machine-agents.md)
+  1. [Rotate credentials](how-to/rotate-credentials.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)
   1. [Configurations](reference/configurations.md)

From 92e8f3db5bf33b3deefd930848bb0a7d2739a847 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 19 Apr 2024 17:59:07 +0000
Subject: [PATCH 3/9] modified: docs/index.md // new:
 docs/how-to/integrate-with-iam.md

---
 docs/how-to/integrate-with-iam.md | 39 +++++++++++++++++++++++++++++++
 docs/index.md                     |  4 ++++
 2 files changed, 43 insertions(+)
 create mode 100644 docs/how-to/integrate-with-iam.md

diff --git a/docs/how-to/integrate-with-iam.md b/docs/how-to/integrate-with-iam.md
new file mode 100644
index 00000000..d82b8984
--- /dev/null
+++ b/docs/how-to/integrate-with-iam.md
@@ -0,0 +1,39 @@
+# How to integrate with IAM
+
+This charm supports integration with the [IAM bundle](https://charmhub.io/iam) via [Oathkeeper](https://charmhub.io/oathkeeper), adding an authentication layer that will front the Jenkins applications. When enabled, Jenkins authentication will be disabled.
+
+The steps to enable this mechanism are described below.
+
+## Deploy the IAM bundle
+
+To deploy the IAM bundle, follow [the corresponding section of the tutorial](https://charmhub.io/topics/canonical-identity-platform/tutorials/e2e-tutorial#heading--0001) and configure it with the Identity Provider of your choice, as described in [the documentation](https://charmhub.io/topics/canonical-identity-platform/tutorials/e2e-tutorial#heading--0002).
+
+## Deploy Oathkeeper
+
+Oathkeeper will interface between Jenkins and the IAM bundle. You will need to deploy the charm and issue and configure TLS certificates for in-cluster communication. Note that the [self-signed-certificates charm](https://charmhub.io/self-signed-certificates) is already deployed as part of the IAM bundle.
+
+```
+juju deploy oathkeeper --channel edge --trust
+juju integrate oathkeeper:certificates self-signed-certificates
+```
+
+To leverage proxy authentication, enable traefik's `enable_experimental_forward_auth` feature and integrate the traefik charm instance with Oathkeeper. As earlier, traefik-public is already deployed as part of the bundle.
+```
+juju config traefik-public enable_experimental_forward_auth=True
+juju integrate oathkeeper traefik-public:experimental-forward-auth
+```
+
+Finally, integrate Oathkeeper with [Kratos](https://charmhub.io/kratos), the User Management system, also part of the IAM bundle.
+```
+juju integrate oathkeeper kratos
+```
+
+## Configure the Jenkins charm
+
+Jenkins needs to be accessible via the same ingress in which Oathkeeper has been configured for the requests to be redirected, so upon integrating with it and with Oathkeeper itself. Authentication is set up in place.
+```
+juju integrate jenkins-k8s:ingress traefik-public
+juju integrate oathkeeper jenkins-k8s:auth-proxy
+```
+
+Now Jenkins will be reachable at https://[public_ip]/[model_name]-jenkins-k8s, where `public_ip` is the load balancer IP assigned to the traefik charm and `model_name`, the model where Jenkins is deployed.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 62a19385..20a59bc9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -26,8 +26,12 @@ Thinking about using the Jenkins-k8s Operator for your next project? [Get in tou
 1. [How to](how-to)
   1. [Configure restart-time-range](how-to/configure-restart-time-range.md)
   1. [How to configure installable plugins](how-to/configure-installable-plugins.md)
+  1. [How to control heap memory of the jenkins-k8s-operator charm](how-to/configure-jenkins-memory-usage.md)
   1. [Get admin password](how-to/get-admin-password.md)
+  1. [How to integrate with external agent charms](how-to/integrate-with-external-agents.md)
+  1. [How to integrate with IAM](how-to/integrate-with-iam.md)
   1. [How to integrate with machine agents](how-to/integrate-with-machine-agents.md)
+  1. [How to resize the jenkins-home storage volume](how-to/resize-jenkins-storage.md)
   1. [Rotate credentials](how-to/rotate-credentials.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)

From bbbfdcaf6ac2a1e0ff72662eefcfac9146f2d81e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 30 Apr 2024 03:46:08 +0000
Subject: [PATCH 4/9] modified: docs/how-to/integrate-with-iam.md

---
 docs/how-to/integrate-with-iam.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/how-to/integrate-with-iam.md b/docs/how-to/integrate-with-iam.md
index ebfc185f..d82b8984 100644
--- a/docs/how-to/integrate-with-iam.md
+++ b/docs/how-to/integrate-with-iam.md
@@ -36,4 +36,4 @@ juju integrate jenkins-k8s:ingress traefik-public
 juju integrate oathkeeper jenkins-k8s:auth-proxy
 ```
 
-Now Jenkins will be reachable at https://[public_ip]/[model_name]-jenkins-k8s, where `public_ip` is the load balancer IP assigned to the traefik charm and `model_name`, the model where Jenkins is deployed.
+Now Jenkins will be reachable at https://[public_ip]/[model_name]-jenkins-k8s, where `public_ip` is the load balancer IP assigned to the traefik charm and `model_name`, the model where Jenkins is deployed.
\ No newline at end of file

From 30797ad9470f4a5e398e10d5df4fb30b8668bcd5 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 30 Apr 2024 13:21:30 +0000
Subject: [PATCH 5/9] modified: docs/how-to/resize-jenkins-storage.md

---
 docs/how-to/resize-jenkins-storage.md | 49 +++++++++++++++------------
 1 file changed, 28 insertions(+), 21 deletions(-)

diff --git a/docs/how-to/resize-jenkins-storage.md b/docs/how-to/resize-jenkins-storage.md
index a989a7c7..f7e85a1c 100644
--- a/docs/how-to/resize-jenkins-storage.md
+++ b/docs/how-to/resize-jenkins-storage.md
@@ -10,37 +10,43 @@ From [Backing-up/Restoring Jenkins](https://www.jenkins.io/doc/book/system-admin
 * Plugins (`.hpi` and `.jpi` files) in the `./plugins` folder
 
 ```bash
+echo cat <<EOF > backup.sh
 #!/bin/bash
 export JENKINS_HOME=/var/lib/jenkins
 export JENKINS_BACKUP=/mnt/backup
 
-echo "running backup as $(whoami) in $(pwd)"
-mkdir -p $JENKINS_BACKUP
-cp $JENKINS_HOME/secrets/master.key $JENKINS_BACKUP
-cp -r $JENKINS_HOME/*.xml $JENKINS_BACKUP
-cp -r $JENKINS_HOME/jobs $JENKINS_BACKUP
-cp -r $JENKINS_HOME/builds $JENKINS_BACKUP
-cp -r $JENKINS_HOME/workspace $JENKINS_BACKUP
-mkdir -p $JENKINS_BACKUP/plugins
-cp -r $JENKINS_HOME/plugins/*.hpi $JENKINS_BACKUP/plugins
-cp -r $JENKINS_HOME/plugins/*.jpi $JENKINS_BACKUP/plugins
+echo "running backup as \$(whoami) in \$(pwd)"
+mkdir -p \$JENKINS_BACKUP
+cp \$JENKINS_HOME/secrets/master.key \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/*.xml \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/jobs \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/builds \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/workspace \$JENKINS_BACKUP
+mkdir -p \$JENKINS_BACKUP/plugins
+cp -r \$JENKINS_HOME/plugins/*.hpi \$JENKINS_BACKUP/plugins
+cp -r \$JENKINS_HOME/plugins/*.jpi \$JENKINS_BACKUP/plugins
 
 chown -R 2000:2000 $JENKINS_BACKUP
 tar zcvf jenkins_backup.tar.gz --directory=/mnt backup
+EOF
+
+chmod +x backup.sh
 ```
 1. Transfer the backup script above to the running unit of the Jenkins-k8s charm and run it
 ```bash
-juju scp --container jenkins ./backup.sh jenkins-k8s/0:/backup.sh
-juju ssh  --container jenkins jenkins-k8s/0 /bin/bash
-bash /backup.sh
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins ./backup.sh $JENKINS_UNIT:/backup.sh
+juju ssh  --container jenkins $JENKINS_UNIT /backup.sh
 ```
 2. Retrieve the compressed backup file
 ```bash
-juju scp --container jenkins jenkins-k8s/0:/backup/jenkins_backup.tar.gz jenkins_backup.tar.gz
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins $JENKINS_UNIT:/jenkins_backup.tar.gz jenkins_backup.tar.gz
 ```
 3. With the data backed-up, we can remove the jenkins-k8s application.
 ```bash
-juju remove-application jenkins-k8s
+JENKINS_APP=jenkins-k8s
+juju remove-application $JENKINS_APP
 ```
 
 ## Restore the backup on a new charm instance
@@ -50,13 +56,14 @@ juju deploy jenkins-k8s --storage jenkins-home=10GB
 ```
 2. Wait for the charm to be ready, then restore the backup on the new unit.
 ```bash
-juju scp --container jenkins ./jenkins_backup.tar.gz jenkins-k8s/0:/jenkins_backup.tar.gz
-tar zxvf jenkins_backup.tar.gz
-chown -R 2000:2000 /backup
-cp -R /backup/* /var/lib/jenkins
-rm -rf /backup /jenkins_backup.tar.gz
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins ./jenkins_backup.tar.gz $JENKINS_UNIT:/jenkins_backup.tar.gz
+juju ssh --container jenkins $JENKINS_UNIT tar zxvf jenkins_backup.tar.gz
+juju ssh --container jenkins $JENKINS_UNIT chown -R 2000:2000 /backup
+juju ssh --container jenkins $JENKINS_UNIT cp -R /backup/* /var/lib/jenkins
+juju ssh --container jenkins $JENKINS_UNIT rm -rf /backup /jenkins_backup.tar.gz
 ```
 3. Finally restart pebble
 ```bash
-pebble restart jenkins
+juju ssh --container jenkins $JENKINS_UNIT pebble restart jenkins
 ```
\ No newline at end of file

From bfc05ea86a7b9676fbf78bbe8c59b41d69d1e5fe Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 30 Apr 2024 17:39:11 +0000
Subject: [PATCH 6/9] modified: docs/how-to/resize-jenkins-storage.md

---
 docs/how-to/resize-jenkins-storage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/how-to/resize-jenkins-storage.md b/docs/how-to/resize-jenkins-storage.md
index 05baeb89..f7e85a1c 100644
--- a/docs/how-to/resize-jenkins-storage.md
+++ b/docs/how-to/resize-jenkins-storage.md
@@ -66,4 +66,4 @@ juju ssh --container jenkins $JENKINS_UNIT rm -rf /backup /jenkins_backup.tar.gz
 3. Finally restart pebble
 ```bash
 juju ssh --container jenkins $JENKINS_UNIT pebble restart jenkins
-```
+```
\ No newline at end of file

From 115b3e3eb7322dd515374a6b521712ac1d24cf60 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 11 Jun 2024 08:41:48 +0000
Subject: [PATCH 7/9] modified:
 docs/index.md,docs/how-to/resize-jenkins-storage.md // new:
 docs/how-to/backup-and-restore-jenkins.md

---
 docs/how-to/backup-and-restore-jenkins.md | 61 +++++++++++++++++++
 docs/how-to/resize-jenkins-storage.md     | 71 +++--------------------
 docs/index.md                             |  3 +
 3 files changed, 73 insertions(+), 62 deletions(-)
 create mode 100644 docs/how-to/backup-and-restore-jenkins.md

diff --git a/docs/how-to/backup-and-restore-jenkins.md b/docs/how-to/backup-and-restore-jenkins.md
new file mode 100644
index 00000000..01e122d6
--- /dev/null
+++ b/docs/how-to/backup-and-restore-jenkins.md
@@ -0,0 +1,61 @@
+# Backup and restore Jenkins
+A backup is a snapshot of the Jenkins data (jobs, configurations, secrets, plugins, etc.) at a given point in time. This backup can be used to:
+* Restore Jenkins to a previous stable state (during disaster recovery).
+* Migrate data to a new Jenkins charm instance.
+
+## Create a backup
+1. Create the backup script
+From [Backing-up/Restoring Jenkins](https://www.jenkins.io/doc/book/system-administration/backing-up/), This script backs up the most essential files as mentioned in the article:
+* The `master.key` file.
+* Job-related files in the `./jobs`, `./builds` and `./workspace` folders.
+* Plugins (`.hpi` and `.jpi` files) in the `./plugins` folder
+
+```bash
+cat <<EOF > backup.sh
+#!/bin/bash
+export JENKINS_HOME=/var/lib/jenkins
+export JENKINS_BACKUP=/mnt/backup
+
+echo "running backup as \$(whoami) in \$(pwd)"
+mkdir -p \$JENKINS_BACKUP
+cp \$JENKINS_HOME/secrets/master.key \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/jobs \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/builds \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/workspace \$JENKINS_BACKUP
+mkdir -p \$JENKINS_BACKUP/plugins
+cp -r \$JENKINS_HOME/plugins/*.hpi \$JENKINS_BACKUP/plugins
+cp -r \$JENKINS_HOME/plugins/*.jpi \$JENKINS_BACKUP/plugins
+
+chown -R 2000:2000 \$JENKINS_BACKUP
+tar zcvf jenkins_backup.tar.gz --directory=/mnt backup
+EOF
+
+chmod +x backup.sh
+```
+2. Transfer the backup script above to the running unit of the Jenkins-k8s charm and run it
+```bash
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins ./backup.sh $JENKINS_UNIT:/backup.sh
+juju ssh  --container jenkins $JENKINS_UNIT /backup.sh
+```
+3. Retrieve the compressed backup file
+```bash
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins $JENKINS_UNIT:/jenkins_backup.tar.gz jenkins_backup.tar.gz
+```
+You now have the compressed Jenkins data on your host system.
+
+## Restore the backup on a new (or existing) charm instance
+1. Restore the backup on the Jenkins charm unit.
+```bash
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins ./jenkins_backup.tar.gz $JENKINS_UNIT:/jenkins_backup.tar.gz
+juju ssh --container jenkins $JENKINS_UNIT tar zxvf jenkins_backup.tar.gz
+juju ssh --container jenkins $JENKINS_UNIT chown -R jenkins:jenkins /backup
+juju ssh --container jenkins $JENKINS_UNIT cp -avR /backup/* /var/lib/jenkins
+juju ssh --container jenkins $JENKINS_UNIT rm -rf /backup /jenkins_backup.tar.gz
+```
+2. Restart pebble for the changes to take effect
+```bash
+juju ssh --container jenkins $JENKINS_UNIT pebble restart jenkins
+```
\ No newline at end of file
diff --git a/docs/how-to/resize-jenkins-storage.md b/docs/how-to/resize-jenkins-storage.md
index f7e85a1c..711fb8ba 100644
--- a/docs/how-to/resize-jenkins-storage.md
+++ b/docs/how-to/resize-jenkins-storage.md
@@ -1,69 +1,16 @@
 # How to resize the jenkins-home storage volume
-The default size of the jenkins-home storage volume for a fresh installation is 1GB. While this works for most scenarios, operators might need to have more storage for installing plugins, storing artifacts, and runninng builds/checking out SCMs on the built-in node.
+The default size of the jenkins-home storage volume for a fresh installation is 1GB. While this works for most scenarios, operators might need to have more storage for installing plugins, storing artifacts, and running builds/checking out SCMs on the built-in node.
 
-A low disk-space on the built-in node will cause the node to go offline, blocking jenkins from running jobs.
+A low disk-space on the built-in node will cause the node to go offline, blocking Jenkins from running jobs.
 
-## Create a backup
-From [Backing-up/Restoring Jenkins](https://www.jenkins.io/doc/book/system-administration/backing-up/), This script backs up the most essential files as mentioned in the article:
-* The `master.key` file.
-* Job-related files in the `./jobs`, `./builds` and `./workspace` folders.
-* Plugins (`.hpi` and `.jpi` files) in the `./plugins` folder
+### Create a backup of the current Jenkins charm instance
+Follow the `Create a backup` section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system
 
+### Deploy the new Jenkins charm instance, specifying the size of the storage volume
+Create a new application with the `--storage` flag. In this example we'll deploy the charm with a storage of 10GB
 ```bash
-echo cat <<EOF > backup.sh
-#!/bin/bash
-export JENKINS_HOME=/var/lib/jenkins
-export JENKINS_BACKUP=/mnt/backup
-
-echo "running backup as \$(whoami) in \$(pwd)"
-mkdir -p \$JENKINS_BACKUP
-cp \$JENKINS_HOME/secrets/master.key \$JENKINS_BACKUP
-cp -r \$JENKINS_HOME/*.xml \$JENKINS_BACKUP
-cp -r \$JENKINS_HOME/jobs \$JENKINS_BACKUP
-cp -r \$JENKINS_HOME/builds \$JENKINS_BACKUP
-cp -r \$JENKINS_HOME/workspace \$JENKINS_BACKUP
-mkdir -p \$JENKINS_BACKUP/plugins
-cp -r \$JENKINS_HOME/plugins/*.hpi \$JENKINS_BACKUP/plugins
-cp -r \$JENKINS_HOME/plugins/*.jpi \$JENKINS_BACKUP/plugins
-
-chown -R 2000:2000 $JENKINS_BACKUP
-tar zcvf jenkins_backup.tar.gz --directory=/mnt backup
-EOF
-
-chmod +x backup.sh
-```
-1. Transfer the backup script above to the running unit of the Jenkins-k8s charm and run it
-```bash
-JENKINS_UNIT=jenkins-k8s/0
-juju scp --container jenkins ./backup.sh $JENKINS_UNIT:/backup.sh
-juju ssh  --container jenkins $JENKINS_UNIT /backup.sh
-```
-2. Retrieve the compressed backup file
-```bash
-JENKINS_UNIT=jenkins-k8s/0
-juju scp --container jenkins $JENKINS_UNIT:/jenkins_backup.tar.gz jenkins_backup.tar.gz
-```
-3. With the data backed-up, we can remove the jenkins-k8s application.
-```bash
-JENKINS_APP=jenkins-k8s
-juju remove-application $JENKINS_APP
+juju deploy jenkins-k8s-new --storage jenkins-home=10GB
 ```
 
-## Restore the backup on a new charm instance
-1. When the application has been deleted, create a new application with the `--storage` flag. In this example we'll deploy the charm with a storage of 10GB
-```bash
-juju deploy jenkins-k8s --storage jenkins-home=10GB
-```
-2. Wait for the charm to be ready, then restore the backup on the new unit.
-```bash
-JENKINS_UNIT=jenkins-k8s/0
-juju scp --container jenkins ./jenkins_backup.tar.gz $JENKINS_UNIT:/jenkins_backup.tar.gz
-juju ssh --container jenkins $JENKINS_UNIT tar zxvf jenkins_backup.tar.gz
-juju ssh --container jenkins $JENKINS_UNIT chown -R 2000:2000 /backup
-juju ssh --container jenkins $JENKINS_UNIT cp -R /backup/* /var/lib/jenkins
-juju ssh --container jenkins $JENKINS_UNIT rm -rf /backup /jenkins_backup.tar.gz
-```
-3. Finally restart pebble
-```bash
-juju ssh --container jenkins $JENKINS_UNIT pebble restart jenkins
-```
\ No newline at end of file
+### Restore the created backup onto the newly created Jenkins charm instance
+Follow the `Restore the backup on a new (or existing) charm instance` section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system. Remember to update the `JENKINS_UNIT` environment variable. For our example we have `JENKINS_UNIT=jenkins-k8s-new/0`
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 20a59bc9..63ac5cf9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -25,17 +25,20 @@ Thinking about using the Jenkins-k8s Operator for your next project? [Get in tou
   1. [Getting Started](tutorial/getting-started.md)
 1. [How to](how-to)
   1. [Configure restart-time-range](how-to/configure-restart-time-range.md)
+  1. [Backup and restore Jenkins](how-to/backup-and-restore-jenkins.md)
   1. [How to configure installable plugins](how-to/configure-installable-plugins.md)
   1. [How to control heap memory of the jenkins-k8s-operator charm](how-to/configure-jenkins-memory-usage.md)
   1. [Get admin password](how-to/get-admin-password.md)
   1. [How to integrate with external agent charms](how-to/integrate-with-external-agents.md)
   1. [How to integrate with IAM](how-to/integrate-with-iam.md)
   1. [How to integrate with machine agents](how-to/integrate-with-machine-agents.md)
+  1. [How to redeploy Jenkins](how-to/redeploy.md)
   1. [How to resize the jenkins-home storage volume](how-to/resize-jenkins-storage.md)
   1. [Rotate credentials](how-to/rotate-credentials.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)
   1. [Configurations](reference/configurations.md)
+  1. [External access](reference/external-access.md)
   1. [Integrations](reference/integrations.md)
 1. [Explanation](explanation)
   1. [Agent-deprecated relation](explanation/agent-deprecated-relation.md)
\ No newline at end of file

From cfbe8ceab48a62c46e9927818b30bed8146fe73b Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 7 Nov 2024 04:47:24 +0000
Subject: [PATCH 8/9] modified:
 docs/how-to/configure-jenkins-memory-usage.md,docs/how-to/configure-installable-plugins.md,docs/reference/configurations.md,docs/tutorial/getting-started.md,docs/how-to/resize-jenkins-storage.md,docs/reference/actions.md,docs/reference/integrations.md
 // new: docs/reference/external-access.md,docs/how-to/redeploy.md

---
 docs/how-to/configure-installable-plugins.md  |  23 +--
 docs/how-to/configure-jenkins-memory-usage.md |   6 +-
 docs/how-to/redeploy.md                       |  13 ++
 docs/how-to/resize-jenkins-storage.md         |   6 +-
 docs/reference/actions.md                     |   4 +-
 docs/reference/configurations.md              |   4 +-
 docs/reference/external-access.md             |  19 ++
 docs/reference/integrations.md                |  48 +++--
 docs/tutorial/getting-started.md              | 177 ++++++++++++++----
 9 files changed, 232 insertions(+), 68 deletions(-)
 create mode 100644 docs/how-to/redeploy.md
 create mode 100644 docs/reference/external-access.md

diff --git a/docs/how-to/configure-installable-plugins.md b/docs/how-to/configure-installable-plugins.md
index 8b0df51e..57474361 100644
--- a/docs/how-to/configure-installable-plugins.md
+++ b/docs/how-to/configure-installable-plugins.md
@@ -2,21 +2,22 @@
 
 ### Configure `plugins`
 
-Use the `plugins` configuration to allow a list of plugins to be installed on Jenkins.
-Comma-separated list of allowed plugin short names. If empty, any plugin can be installed.
-Plugins installed by the user and their dependencies will be removed automatically if not on
+Use the `plugins` configuration to allow plugins to be installed on Jenkins.
+The configuration is a comma-separated list of allowed plugin short names. If empty, any plugin can be installed.
+Plugins installed by the user and the plugins' dependencies will be removed automatically if they are not on
 the list. Included plugins are not automatically installed.
-The plugins are cleaned up at `update-status` hook trigger. If the `restart-time-range`
-configuration option is provided, the plugins are cleaned up during the defined time range.
-
-On trigger it will:
-
-1. Delete any installed plugins not defined on the list and their dependencies.
-2. Set a system message on Jenkins indicating which user installed plugins have been deleted.
 
 ```
 juju config jenkins-k8s plugins=<allowed-plugins-csv>
 
 # plugins example: `git, azure-cli, aws-credentials` will allow git, azure and aws-credentials
 plugins to be installed.
-```
\ No newline at end of file
+```
+
+The plugins are cleaned up at `update-status` hook trigger. If the `restart-time-range`
+configuration option is provided, the plugins are cleaned up during the defined time range.
+
+On trigger it will:
+
+1. Delete any installed plugins not defined on the list and their dependencies.
+2. Set a system message on Jenkins indicating which user installed plugins have been deleted.
\ No newline at end of file
diff --git a/docs/how-to/configure-jenkins-memory-usage.md b/docs/how-to/configure-jenkins-memory-usage.md
index 4867718d..3bc39832 100644
--- a/docs/how-to/configure-jenkins-memory-usage.md
+++ b/docs/how-to/configure-jenkins-memory-usage.md
@@ -1,5 +1,5 @@
 # How to control heap memory of the jenkins-k8s-operator charm
-The [jenkins-k8s-operator](https://github.com/canonical/jenkins-k8s-operator) charm uses [juju constraints](https://juju.is/docs/juju/constraint) to limit the amount of memory a charm can use. To deploy the charm with constraints, use the `--constraints "<key>=<value>"` option when running `juju deploy`:
+The [jenkins-k8s-operator](https://github.com/canonical/jenkins-k8s-operator) charm uses [Juju constraints](https://juju.is/docs/juju/constraint) to limit the amount of memory a charm can use. To deploy the charm with constraints, use the `--constraints "<key>=<value>"` option when running `juju deploy`:
 ```bash
 juju deploy jenkins-k8s --channel=latest/edge --constraints "mem=2048M"
 ```
@@ -9,5 +9,5 @@ juju set-constraints jenkins-k8s "mem=4096M"
 ```
 Other types of constraints (like cores, disk, etc.) can also be applied. Note that this value affects the shared maximum memory between the `charm` container and `jenkins` container.
 
-# Considerations when applying memory constraints
-Constraints set this way directly influence the amount of heap memory available to the JVM, with a ratio `JVM heap / Container Memory limit` of 0.5. For example, a `jenkins-k8s-operator` charm deployed with `--constraints "mem=1024M"` would set a maximum heap memory size of 512Mb. Too little heap memory can result in the controller getting restarted due to Out-of-memory(OOM) error. Make sure to adapt the memory constraints based on your workload.
\ No newline at end of file
+## Considerations when applying memory constraints
+Constraints set this way directly influence the amount of heap memory available to the JVM, with a ratio `JVM heap / Container Memory limit` of 0.5. For example, a `jenkins-k8s-operator` charm deployed with `--constraints "mem=1024M"` would set a maximum heap memory size of 512Mb. Too little heap memory can result in the controller getting restarted due to Out-of-memory (OOM) error. Make sure to adapt the memory constraints based on your workload.
\ No newline at end of file
diff --git a/docs/how-to/redeploy.md b/docs/how-to/redeploy.md
new file mode 100644
index 00000000..e1aadf6e
--- /dev/null
+++ b/docs/how-to/redeploy.md
@@ -0,0 +1,13 @@
+# How to redeploy Jenkins
+
+Redeployment is a process where the old charm instance is removed and data is migrated to a new charm instance. Redeploying the Jenkins charm consists of 3 steps:
+
+1. Create the new Jenkins charm instance:
+```bash
+juju deploy jenkins-k8s jenkins-k8s-new
+```
+2. Migrate Jenkins data: Follow the instructions in [the charm's documentation for backup and restore](https://charmhub.io/jenkins-k8s/docs/how-to-backup-and-restore-jenkins).
+3. Remove the old Jenkins charm instance:
+```bash
+juju remove-application jenkins-k8s
+```
\ No newline at end of file
diff --git a/docs/how-to/resize-jenkins-storage.md b/docs/how-to/resize-jenkins-storage.md
index 711fb8ba..4eb7882e 100644
--- a/docs/how-to/resize-jenkins-storage.md
+++ b/docs/how-to/resize-jenkins-storage.md
@@ -4,13 +4,13 @@ The default size of the jenkins-home storage volume for a fresh installation is
 A low disk-space on the built-in node will cause the node to go offline, blocking Jenkins from running jobs.
 
 ### Create a backup of the current Jenkins charm instance
-Follow the `Create a backup` section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system
+Follow the "Create a backup" section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/how-to-backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system
 
 ### Deploy the new Jenkins charm instance, specifying the size of the storage volume
-Create a new application with the `--storage` flag. In this example we'll deploy the charm with a storage of 10GB
+Create a new application with the `--storage` flag. In this example we'll deploy the charm with a storage of 10GB:
 ```bash
 juju deploy jenkins-k8s-new --storage jenkins-home=10GB
 ```
 
 ### Restore the created backup onto the newly created Jenkins charm instance
-Follow the `Restore the backup on a new (or existing) charm instance` section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system. Remember to update the `JENKINS_UNIT` environment variable. For our example we have `JENKINS_UNIT=jenkins-k8s-new/0`
\ No newline at end of file
+Follow the "Restore the backup on a new (or existing) charm instance" section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/how-to-backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system. Remember to update the `JENKINS_UNIT` environment variable. For our example we have `JENKINS_UNIT=jenkins-k8s-new/0`.
\ No newline at end of file
diff --git a/docs/reference/actions.md b/docs/reference/actions.md
index 8cb2adbf..1482aed7 100644
--- a/docs/reference/actions.md
+++ b/docs/reference/actions.md
@@ -1,3 +1,5 @@
 # Actions
 
-See [Actions](https://charmhub.io/jenkins-k8s/actions).
\ No newline at end of file
+See [Actions](https://charmhub.io/jenkins-k8s/actions).
+
+> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)
\ No newline at end of file
diff --git a/docs/reference/configurations.md b/docs/reference/configurations.md
index 8d84fbe4..53e0c0c7 100644
--- a/docs/reference/configurations.md
+++ b/docs/reference/configurations.md
@@ -1,3 +1,5 @@
 # Configurations
 
-See [Configure](https://charmhub.io/jenkins-k8s/configure).
\ No newline at end of file
+See [Configurations](https://charmhub.io/jenkins-k8s/configure).
+
+> Read more about configurations in the Juju docs: [Configuration](https://juju.is/docs/juju/configuration)
\ No newline at end of file
diff --git a/docs/reference/external-access.md b/docs/reference/external-access.md
new file mode 100644
index 00000000..0db5ca31
--- /dev/null
+++ b/docs/reference/external-access.md
@@ -0,0 +1,19 @@
+# External access
+The Jenkins charm requires access to the following domains to install Jenkins and its plugins:
+
+* `jenkins-ci.org`
+* `updates.jenkins-ci.org`
+* `jenkins.io`
+* `updates.jenkins.io`
+* `.mirrors.jenkins-ci.org`
+* `fallback.get.jenkins.io`
+* `get.jenkins.io`
+* `pkg.jenkins.io`
+* `archives.jenkins.io`
+* `pkg.origin.jenkins.io`
+* `.mirrors.jenkins.io`
+* `www.jenkins.io`
+
+Depending on the localisation, some region-specific external mirrors might also be used. You can find more information on the [list of mirrors for Jenkins](https://get.jenkins.io/war/2.456/jenkins.war?mirrorstats).
+
+Some plugins can also require external access, such as `github.com` for the [Github branch source plugin](https://plugins.jenkins.io/github-branch-source/) or an external Kubernetes cluster if you are using the [Kubernetes plugin](https://plugins.jenkins.io/kubernetes/). Refer to the plugin's documentation for more details.
\ No newline at end of file
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
index 998d25f7..071711f9 100644
--- a/docs/reference/integrations.md
+++ b/docs/reference/integrations.md
@@ -2,45 +2,57 @@
 
 ### agent
 
-_Interface_: jenkins_agent_v0
+_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`
+Example agent integrate 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`
+```
+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`
+```
+juju integrate 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`
+```
+juju integrate jenkins-k8s:agent localhost:admin/jenkins-vm-model.jenkins-agent
+```
 
 ### logging
 
-_Interface_: loki_push_api
+_Interface_: loki_push_api    
 _Supported charms_: [loki-k8s](https://charmhub.io/loki-k8s)
 
 Logging relation provides a way to scrape logs produced from the Jenkins server charm. The Jenkins 
-server logs are stored at `/var/lib/jenkins/jenkins.log`. These logs are the same logs as the logs 
+server logs are stored at `/var/lib/jenkins/logs/jenkins.log`. These logs are the same logs as the logs 
 emitted to the standard output. A promtail worker is spawned and will periodically push logs to
 Loki.
 
-Example agent relate command: `juju relate jenkins-k8s:logging loki-k8s:logging`
+Example agent integrate command: 
+```
+juju integrate jenkins-k8s:logging loki-k8s:logging
+```
 
 ### metrics-endpoint
 
-_Interface_: prometheus_scrape
+_Interface_: prometheus_scrape    
 _Supported charms_: [prometheus-k8s](https://charmhub.io/prometheus-k8s)
 
 Metrics-endpoint relation allows scraping the `/prometheus` endpoint provided by Jenkins
@@ -50,12 +62,14 @@ only be scraped by Prometheus once the relation becomes active. For more informa
 metrics exposed, please refer to the
 [`prometheus` plugin documentation](https://plugins.jenkins.io/prometheus/).
 
-Example metrics-endpoint relate command: 
-`juju relate jenkins-k8s:metrics-endpoint prometheus-k8s:metrics-endpoint`
+Example metrics-endpoint integrate command: 
+```
+juju integrate jenkins-k8s:metrics-endpoint prometheus-k8s:metrics-endpoint
+```
 
 ### grafana-dashboard
 
-_Interface_: 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 
@@ -65,5 +79,11 @@ Performance and Health Overview” under the General section of the dashboard br
 (`/dashboards`). Modifications to the dashboard can be made but will not be persisted upon
 restart/redeployment of the charm.
 
-Grafana-Prometheus relate command: `juju relate grafana-k8s:grafana-source prometheus-k8s:grafana-source`
-Grafana-dashboard relate command: `juju relate jenkins-k8s:grafana-dashboard grafana-k8s:grafana-dashboard`
\ No newline at end of file
+Grafana-Prometheus integrate command: 
+```
+juju integrate grafana-k8s:grafana-source prometheus-k8s:grafana-source
+```
+Grafana-dashboard integrate command: 
+```
+juju integrate jenkins-k8s:grafana-dashboard grafana-k8s:grafana-dashboard
+```
\ No newline at end of file
diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md
index 9d0ebc2a..3bb02309 100644
--- a/docs/tutorial/getting-started.md
+++ b/docs/tutorial/getting-started.md
@@ -1,27 +1,32 @@
-# Getting Started
+# Deploy the jenkins-k8s charm for the first time
 
 ## 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)
+- Access the UI
+- Deploy and integrate agents
 
 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.
+tutorial will walk through each step of deployment to get a basic Jenkins server deployment.
 
-### Prerequisites
+### Requirements
 
-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).
+- A machine with amd64 architecture.
+- Juju 3 installed.
+- Juju MicroK8s controller created and active named `microk8s`. [MetalLB addon](https://microk8s.io/docs/addon-metallb) should be enabled for traefik-k8s to work.
+- LXD controller created and active named `lxd` (optional).
+- All the requirements can be met using the [Multipass charm-dev blueprint](https://juju.is/docs/juju/set-up--tear-down-your-test-environment#heading--set-up---tear-down-automatically). Use the Multipass VM shell to run all commands in this tutorial.
 
-### Setting up the tutorial model
+For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
+
+### Set 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.
+set up a new Juju model in the `microk8s` controller with the following command.
 
 ```
+juju switch microk8s
 juju add-model jenkins-tutorial
 ```
 
@@ -31,14 +36,84 @@ Start off by deploying the jenkins-k8s charm. By default it will deploy the late
 of the jenkins-k8s charm.
 
 ```
-# Deploy an edge version of the charm until stable version is released.
 juju deploy jenkins-k8s --channel=latest/edge
 ```
 
+Wait for the charm to be active:
+```
+juju wait-for application jenkins-k8s
+```
+
 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
+
+### Expose jenkins-k8s through ingress
+
+Deploy traefik-k8s charm and integrate it with the jenkins-k8s charm:
+```
+juju deploy traefik-k8s --channel=latest/edge --trust
+juju integrate jenkins-k8s:ingress traefik-k8s
+```
+
+You can check the status with:
+```
+juju status --relations
+```
+
+After a few minutes, the deployment will be finished and all the units should be in 
+the active status.
+
+Run the following command to get the URL to connect to Jenkins:
+```
+juju run traefik-k8s/0 show-proxied-endpoints --format=yaml
+```
+
+The output will be something similar to:
+```
+Running operation 1 with 1 task
+  - task 2 on unit-traefik-k8s-0
+
+Waiting for task 2...
+traefik-k8s/0: 
+  id: "2"
+  results: 
+    proxied-endpoints: '{"traefik-k8s": {"url": "http://10.12.97.102"}, "jenkins-k8s":
+      {"url": "http://10.12.97.102/jenkins-tutorial-jenkins-k8s"}}'
+    return-code: 0
+  status: completed
+  timing: 
+    completed: 2024-09-27 15:09:36 +0200 CEST
+    enqueued: 2024-09-27 15:09:35 +0200 CEST
+    started: 2024-09-27 15:09:35 +0200 CEST
+  unit: traefik-k8s/0
+```
+
+In this case, the URL to use in your browser will be `http://10.12.97.102/jenkins-tutorial-jenkins-k8s`. In
+your case it will probably be a different IP address.
+
+By running the `get-admin-password` action on the jenkins-k8s unit, Juju will read and fetch the
+admin credentials setup for you. You can use the following command below.
+
+```
+juju run jenkins-k8s/0 get-admin-password 
+```
+
+The output should look something similar to the contents below:
+
+```
+Running operation 3 with 1 task
+  - task 4 on unit-jenkins-k8s-0
+
+Waiting for task 4...
+password: e67a44447d37423887e278bc8c694f95
+```
+
+You can now access your Jenkins server UI at the previous URL, and login using username "admin" and password from the action above.
+
+You may need to wait for up to five minutes for the URL to work correctly.
+
+### Deploy and integrate k8s 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.
@@ -51,45 +126,77 @@ 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
+juju integrate jenkins-k8s:agent jenkins-agent-k8s:agent
+```
+
+You can check the status with:
+```
+juju status --relations
 ```
 
-### Get admin credentials
+After the units are active, the output to the previous command should be similar to:
+```
+Model             Controller  Cloud/Region        Version  SLA          Timestamp
+jenkins-tutorial  microk8s    microk8s/localhost  3.5.3    unsupported  10:27:59+02:00
+
+App                Version  Status  Scale  Charm              Channel      Rev  Address         Exposed  Message
+jenkins-agent-k8s           active      3  jenkins-agent-k8s  latest/edge   27  10.152.183.108  no       
+jenkins-k8s        2.462.2  active      1  jenkins-k8s        latest/edge  125  10.152.183.178  no       
+traefik-k8s        2.11.0   active      1  traefik-k8s        latest/edge  211  10.152.183.40   no       Serving at 10.12.97.102
+
+Unit                  Workload  Agent  Address      Ports  Message
+jenkins-agent-k8s/0   active    idle   10.1.32.148         
+jenkins-agent-k8s/1   active    idle   10.1.32.153         
+jenkins-agent-k8s/2*  active    idle   10.1.32.152         
+jenkins-k8s/0*        active    idle   10.1.32.132         
+traefik-k8s/0*        active    idle   10.1.32.147         Serving at 10.12.97.102
+
+Integration provider     Requirer             Interface         Type     Message
+jenkins-agent-k8s:agent  jenkins-k8s:agent    jenkins_agent_v0  regular  
+traefik-k8s:ingress      jenkins-k8s:ingress  ingress           regular  
+traefik-k8s:peers        traefik-k8s:peers    traefik_peers     peer     
+```
 
-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.
+After a few minutes you should be able to see the jenkins agent K8s model as a new build executor
+in the Jenkins UI.
 
-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.
+
+### Deploy and integrate machine agents (optional)
+
+For this section you need a machine model named `lxd`. If you are using the Multipass, the `charm-dev` blueprint
+will automatically set up the machine model for you.
+
+The first requirement is to create the offer, so the jenkins-k8s agent endpoint is available
+for cross-model integrations.
 
 ```
-juju run-action jenkins-k8s/0 get-admin-password --wait
+juju offer jenkins-k8s:agent
 ```
 
-The output should look something similar to the contents below:
+Once the offer is created, we can create the new model, deploy the machine jenkins-agent charm
+and integrate it with jenkins-k8s with:
+```
+juju add-model --controller=lxd jenkins-tutorial
+juju deploy --model lxd:jenkins-tutorial jenkins-agent --channel=latest/edge
+juju integrate --model lxd:jenkins-tutorial jenkins-agent:agent microk8s:admin/jenkins-tutorial.jenkins-k8s
+```
 
+You can check the status of the lxd model with:
 ```
-unit-jenkins-k8s-0:
-  UnitId: jenkins-k8s/0
-  id: "2"
-  results:
-    password: <password>
-  status: completed
-  timing:
-    completed: <timestamp>
-    enqueued: <timestamp>
-    started: <timestamp>
+juju status --model lxd:jenkins-tutorial --relations
 ```
 
-You can now access your Jenkins server UI at `http://<UNIT_IP>:8080` and login using username
-"admin" and password from the action above.
+After a few minutes you should be able to see the jenkins agent machine model as a new build executor
+in the Jenkins UI.
+
 
 ### 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.
+model environments that you’ve created using the following commands.
+
 
 ```
-juju destroy model jenkins-tutorial -y --release-storage
+juju destroy-model jenkins-tutorial --destroy-storage
+juju destroy-model lxd:jenkins-tutorial --destroy-storage
 ```
\ No newline at end of file

From 06a18dea30620ed281fb6805d628ea8e78d4e69b Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 7 Nov 2024 04:47:56 +0000
Subject: [PATCH 9/9] modified: docs/index.md

---
 docs/index.md | 45 +++++++++++++++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 14 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 63ac5cf9..b9cb6a0f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,38 +2,55 @@
 
 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.
+This charm simplifies initial deployment and 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.
 
 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.
 
+## In this documentation
+
+| | |
+|--|--|
+|  [Tutorials](https://charmhub.io/jenkins-k8s/docs/tutorial-getting-started)</br>  Get started - a hands-on introduction to using the charm for new users </br> |  [How-to guides](https://charmhub.io/jenkins-k8s/docs/how-to-configure-restart-time-range) </br> Step-by-step guides covering key operations and common tasks |
+| [Reference](https://charmhub.io/jenkins-k8s/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/jenkins-k8s/docs/explanation-agent-deprecated-relation) </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, 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/jenkins-k8s-operator/issues).
+
 ## 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)
+- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+- [Contribute](https://github.com/canonical/jenkins-k8s-operator/blob/94521d904be53c5645881fc43ba0b71ff60b9776/CONTRIBUTING.md)
 
-Thinking about using the Jenkins-k8s Operator for your next project? [Get in touch](https://chat.charmhub.io/charmhub/channels/charm-dev)!
+Thinking about using the Jenkins-k8s Operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
 
 # Contents
 
 1. [Tutorial](tutorial)
   1. [Getting Started](tutorial/getting-started.md)
 1. [How to](how-to)
+  1. [Backup and restore](how-to/backup-and-restore-jenkins.md)
+  1. [Configure installable plugins](how-to/configure-installable-plugins.md)
+  1. [Configure Jenkins memory usage](how-to/configure-jenkins-memory-usage.md)
   1. [Configure restart-time-range](how-to/configure-restart-time-range.md)
-  1. [Backup and restore Jenkins](how-to/backup-and-restore-jenkins.md)
-  1. [How to configure installable plugins](how-to/configure-installable-plugins.md)
-  1. [How to control heap memory of the jenkins-k8s-operator charm](how-to/configure-jenkins-memory-usage.md)
   1. [Get admin password](how-to/get-admin-password.md)
-  1. [How to integrate with external agent charms](how-to/integrate-with-external-agents.md)
-  1. [How to integrate with IAM](how-to/integrate-with-iam.md)
-  1. [How to integrate with machine agents](how-to/integrate-with-machine-agents.md)
-  1. [How to redeploy Jenkins](how-to/redeploy.md)
-  1. [How to resize the jenkins-home storage volume](how-to/resize-jenkins-storage.md)
+  1. [Integrate with external agents](how-to/integrate-with-external-agents.md)
+  1. [Integrate with IAM](how-to/integrate-with-iam.md)
+  1. [Integrate with machine agents](how-to/integrate-with-machine-agents.md)
+  1. [Redeploy](how-to/redeploy.md)
+  1. [Resize Jenkins storage](how-to/resize-jenkins-storage.md)
   1. [Rotate credentials](how-to/rotate-credentials.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)