docs: add instance and cluster docs by gabor-boros · Pull Request #11 · open-craft/launchpad-cluster-template

gabor-boros · 2026-02-12T05:24:03Z

[SE-6524]

kaustavb12

Left a few comments, but otherwise LGTM 👍

👍

I tested this: Setup mkdocs in local and read through docs
I read through the code
I checked for accessibility issues
Includes documentation
Added to the Code Drift project board (for backports)

docs/infrastructure/provisioning.md

docs/infrastructure/deprovisioning.md

docs/cluster/backup.md

docs/cluster/restore.md

docs/instances/logging.md

kaustavb12 · 2026-02-16T18:03:12Z

@gabor-boros

One thing I found missing in the new docs was instructions on setting up a cluster repo in github. These can be confusing for a first time user, specially things like setting up actions secrets. Also, we should briefly talk about the different workflows and how to trigger them, plus what are some of the workflow common inputs, such as "strain", "runner label", "phd cli version", etc.

Agrendalath

Thank you for preparing such detailed documentation, @gabor-boros! I left some suggestions.

Agrendalath · 2026-02-20T18:56:04Z

docs/README.md

+uv pip install -r docs/requirements.txt
+```
+
+This creates a virtual environment (`.venv`) at the repository root and installs the MkDocs dependencies, making them available to `uv run` commands.


Nit: if uv is already a prerequisite, we can simply run uvx --with mkdocs-material --with mkdocs-glightbox mkdocs. It does not require any virtualenv or dependency management.
It would be a one-liner in the CI. If needed, we could also pin mkdocs version to avoid automatically upgrading it to 2.0.

Agrendalath · 2026-02-20T18:56:14Z

.github/workflows/docs.yml

+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12


Suggested change

- name: Install uv

uses: astral-sh/setup-uv@v4

- uses: actions/setup-python@v5

with:

python-version: 3.12

- name: Install uv and set the python version

uses: astral-sh/setup-uv@v4

with:

python-version: 3.12

Nit - uv action already sets up Python.

Agrendalath · 2026-02-20T18:57:26Z

.github/workflows/docs.yml

+      - name: Set cache ID
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache
+          restore-keys: |
+            mkdocs-material-


Suggested change

- name: Set cache ID

run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV

- uses: actions/cache@v4

with:

key: mkdocs-material-${{ env.cache_id }}

path: ~/.cache

restore-keys: |

mkdocs-material-

Nit: with these dependencies, running the cache action will take more time than installing everything from scratch with uv.

Agrendalath · 2026-02-20T19:41:08Z

docs/README.md

@@ -0,0 +1,93 @@
+# Documentation
+
+This directory contains the documentation for the Launchpad (Launchpad) cluster template, built with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/).


Are we renaming PHD to Launchpad? Isn't it too close to the name of the website owned by Canonical?

docs/infrastructure/provisioning.md

Agrendalath · 2026-02-20T20:46:17Z

docs/infrastructure/deprovisioning.md

+- **Database Snapshots**: Some cloud providers maintain database snapshots
+- **Storage Buckets**: If buckets weren't destroyed, data may still be accessible


If these are managed by Terraform and not marked with prevent_destroy, they will be deleted. We should probably add a huge red warning at the top of this page.

While I see where are you coming from for this, I believe "infrastructure de-provisioning" and "destroy" are pretty self-explanatory for indicating that something irreversible will happen. also, the descriptions are explicitly telling that resources will be destroyed.

Agrendalath · 2026-02-20T20:48:33Z

docs/instances/logging.md

+
+Open edX services write logs to stdout. Log level and format are controlled by application settings (e.g. Django `LOGGING`, Celery, or environment variables). Adjust these in the instance configuration or in custom settings if you need different verbosity or structure.
+
+To get the application logs, use:


Can we browse all logs from a central place? IIRC, Harmony provisioned an OpenSearch instance.

It depends on Harmony. However, setting that up should not be part of this documentation for the reasons mentioned above; rather, if we feel the need for it, let's update the documentation of Harmony. I wouldn't like to blow up the already monumental scope. Would you be up for opening a task for this under the corresponding epic?

Agrendalath · 2026-02-20T20:52:14Z

docs/instances/configuration.md

+- **Tutor** generates the Kubernetes YAML for the instance (Deployments, Services, Ingress, etc.) from `config.yml`.
+- **Drydock** is a Tutor plugin used in this stack; options such as `DRYDOCK_INIT_JOBS` and `DRYDOCK_REGISTRY_CREDENTIALS` are set in `config.yml`.
+
+Regenerate manifests with Tutor from the instance config and commit the result to the cluster repo so ArgoCD can sync.


Is there a command for this?

The pipelines are doing this, this is just an explanation what will happen. By the way, it is done by tutor config save IIRC. An operator will have nothing to do with this besides kicking off the pipeline.

Agrendalath · 2026-02-20T20:54:54Z

docs/instances/docker-images.md

+## Overview
+
+- **Picasso** provides GitHub Actions workflows to build Docker images from the instance configuration and Tutor/Picasso setup.
+- Image names and tags are typically set in the instance `config.yml` (e.g. `DOCKER_IMAGE_OPENEDX`, `MFE_DOCKER_IMAGE`) and automatically updated by Picasso after a build.


An example config would be nice here.

docs/instances/docker-images.md

SE-6524 Signed-off-by: Gabor Boros <gabor@opencraft.com>

SE-6525 Signed-off-by: Gabor Boros <gabor@opencraft.com>

kaustavb12

LGTM 👍

I tested this: Spun up mkdocs in local and read through the docs
I read through the code

docs/infrastructure/deprovisioning.md

docs/infrastructure/provisioning.md

SE-6524 Co-authored-by: Kaustav Banerjee <kaustav@opencraft.com>

gabor-boros · 2026-02-26T16:38:46Z

The rest of the comments can be resolved in a follow-up PR (or multiple ones). Merging now.

kaustavb12 approved these changes Feb 16, 2026

View reviewed changes

Agrendalath reviewed Feb 20, 2026

View reviewed changes

gabor-boros added 2 commits February 26, 2026 16:13

docs: add instance and cluster docs

b247bb7

SE-6524 Signed-off-by: Gabor Boros <gabor@opencraft.com>

docs: address reviewer comments

3d16dfa

SE-6525 Signed-off-by: Gabor Boros <gabor@opencraft.com>

gabor-boros force-pushed the gabor/add-documentation branch from 67c2a1f to 3d16dfa Compare February 26, 2026 13:39

test: fix the example-com rename assertion

ba44b4b

SE-6525 Signed-off-by: Gabor Boros <gabor@opencraft.com>

gabor-boros force-pushed the gabor/add-documentation branch from 9e929ed to ba44b4b Compare February 26, 2026 13:48

kaustavb12 approved these changes Feb 26, 2026

View reviewed changes

docs/infrastructure/deprovisioning.md Outdated Show resolved Hide resolved

docs/infrastructure/provisioning.md Show resolved Hide resolved

docs: apply suggestions from code review

869cc45

SE-6524 Co-authored-by: Kaustav Banerjee <kaustav@opencraft.com>

gabor-boros merged commit 0e4fe0f into main Feb 26, 2026
2 checks passed

		@@ -0,0 +1,93 @@
		# Documentation

		This directory contains the documentation for the Launchpad (Launchpad) cluster template, built with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/).

		- Database Snapshots: Some cloud providers maintain database snapshots
		- Storage Buckets: If buckets weren't destroyed, data may still be accessible


		Open edX services write logs to stdout. Log level and format are controlled by application settings (e.g. Django `LOGGING`, Celery, or environment variables). Adjust these in the instance configuration or in custom settings if you need different verbosity or structure.

		To get the application logs, use:

Conversation

gabor-boros commented Feb 12, 2026

Uh oh!

kaustavb12 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kaustavb12 commented Feb 16, 2026

Uh oh!

Agrendalath left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kaustavb12 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gabor-boros commented Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants