Spread tests for tutorial

.github/workflows/spread_tests.yaml

@@ -0,0 +1,35 @@
+name: Tests with spread
+
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  run-spread-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        spread_job: ['github-ci:ubuntu-22.04:charm/src-docs/tutorial/code/']
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-go@v5
+        with:
+          check-latest: true
+          go-version: 'stable'
+
+      - name: Install spread
+        run: |
+          go install github.com/snapcore/spread/cmd/spread@latest
+      - name: Run tests
+        run: |
+          sudo adduser --gecos "" --disabled-password ubuntu
+          echo "ubuntu:ubuntu" | sudo chpasswd
+          spread ${{ matrix.spread_job }}
+      - name: Tmate debugging session
+        if: ${{ failure() }}
+        uses: mxschmitt/action-tmate@v3
+        timeout-minutes: 15

charm/docs/tutorial/getting-started.md

@@ -1,40 +1,45 @@
-# Getting Started
+<!-- This tutorial should be updated in the src-docs directory. -->
+
+# Deploy the NetBox charm for the first time
 
 ## What you’ll do
+
 - Deploy the NetBox charm.
 - Integrate with Redis using the redis-k8s charm.
 - Integrate with the PostgreSQL K8s charm.
 - Integrate with S3 for storage.
 - Expose the NetBox charm with Traefik k8s.
 - Create a super user.
 
-Through the process, you'll verify the workload state, and log in to
+Through the process, you’ll verify the workload state, and log in to
 your NetBox instance.
 
 ## Requirements
-- Juju 3 installed.
+
+- Juju 3 installed and bootstrapped to a MicroK8s controller. You can accomplish this process by using a Multipass VM as outlined in this guide: [Set up / Tear down your test environment](https://juju.is/docs/juju/set-up--tear-down-your-test-environment)
 - Juju controller that can create a model of type kubernetes.
 - Read/write access to a S3 compatible server with a bucket created.
 - Configuration compatible with the traefik-k8s charms. In the case of MicroK8S this can be achieved with the metallb addon.
 
 For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
 
+## Set up a Tutorial Model
 
-## Setting up a Tutorial Model
+To manage resources effectively and to separate this tutorial’s workload from
+your usual work, we create a new model using the following command.
 
-To manage resources effectively and to separate this tutorial's workload from
-your usual work, we recommend creating a new model using the following command.
-
-```
+```bash
 juju add-model netbox-tutorial
 ```
 
-## Deploy the NetBox charm
+## Deploy NetBox
 
-Deploy the NetBox charm, with all its mandatory requirements (PostgreSQL, Redis and S3).
+Deploy the NetBox charm, with all its mandatory requirements (PostgreSQL, Redis and S3)
+and with the ingress.
 
-### Deploy the charms:
-```
+### Deploy the NetBox charm
+
+```bash
 juju deploy netbox
 ```
 
@@ -43,73 +48,103 @@
 
 Set the allowed hosts. In this example every host is allowed. For a production environment
 only the used hosts should be allowed.
-```
+
+```bash
 juju config netbox django-allowed-hosts='*'
 ```
 
-### Redis
+### Deploy the Redis charm
 
 NetBox requires Redis to work. You can deploy Redis with redis-k8s:
-```
+
+```bash
 juju deploy redis-k8s --channel=latest/edge
 ```
 
-Integrate redis-k8s with NetBox with:
-```
+Integrate redis-k8s with NetBox:
+
+```bash
 juju integrate redis-k8s netbox
 ```
 
-### Deploy PostgreSQL
+### Deploy the PostgreSQL charm
 
-NetBox requires PostgreSQL to work. Deploy and integrate with:
-```
+NetBox requires PostgreSQL to work. Deploy PostgreSQL and integrate:
+
+```bash
 juju deploy postgresql-k8s --channel 14/stable --trust
 juju integrate postgresql-k8s netbox
 ```
 
-### Deploy s3-integrator
+### Deploy the s3-integrator charm
 
 NetBox requires an S3 integration for the uploaded files. This is because
 the NetBox charm is designed to work in a high availability (HA) configuration.
 This allows uploaded images to be placed on an S3 compatible server instead of
 the local filesystem.
 
-You can configure it with:
-```
+Deploy the s3-integrator charm:
+
+```bash
 juju deploy s3-integrator --channel edge
-juju config s3-integrator endpoint="<aws_endpoing_url>" bucket=<bucket_name> path=<path_in_bucket> region=<region> s3-uri-style=<path_or_host>
+```
+
+Configure the s3-integrator charm with your S3 information, wait for the charm to update and provide the credentials:
+
+```bash
+juju config s3-integrator endpoint="${AWS_ENDPOINT_URL}" bucket="${AWS_BUCKET}" path=/ region="${AWS_REGION}" s3-uri-style="${AWS_URI_STYLE}"
 juju wait-for application s3-integrator --query='name=="s3-integrator" && (status=="active" || status=="blocked")'
-juju run s3-integrator/leader sync-s3-credentials access-key=<aws_access_key_id> secret-key=<aws_secret_access_key>
+juju run s3-integrator/leader sync-s3-credentials access-key="${AWS_ACCESS_KEY_ID}" secret-key="${AWS_SECRET_ACCESS_KEY}"
+```
+
+Once the s3-integrator charm has been deployed, integrate the charm with NetBox:
+
+```bash
 juju integrate s3-integrator netbox
 ```
 
-See the [s3-integrator charmhub page](https://charmhub.io/s3-integrator) for more information.
+See the [s3-integrator Charmhub page](https://charmhub.io/s3-integrator) for more information.
 
-### Deploy traefik-k8s 
+### Deploy the traefik-k8s charm
 
 You need to enable MetalLb if using MicroK8s. See the [traefik-k8s charmhub page](https://charmhub.io/traefik-k8s) for more information.
 
 With the next example, you can configure Traefik using path mode routing:
-```
+
+```bash
 juju deploy traefik-k8s --channel edge --trust
-juju config traefik-k8s external_hostname=<netbox_hostname>
-juju config traefik-k8s routing_mode=path
+juju config traefik-k8s external_hostname=${EXTERNAL_HOSTNAME}
+juju config traefik-k8s routing_mode=${ROUTING_MODE}
 juju integrate traefik-k8s netbox
 ```
 
 If the host `netbox_hostname` can be resolved to the correct IP (the load balancer IP),
-you should be able to browse NetBox in the url http://netbox_hostname/netbox-tutorial-netbox
+you should be able to browse NetBox in the URL http://netbox_hostname/netbox-tutorial-netbox
 
 You can check the proxied endpoints with the command:
-```
+
+```bash
 juju run traefik-k8s/0 show-proxied-endpoints --format=yaml
+# [docs:traefik-show-endpoints-end]
 ```
 
-## Create superuser
-To be able to login to NetBox, you can create a super user with the next command:
-```
-juju run netbox/0 create-superuser username=<admin_username> email=<admin_email>
+## Create a super user
+
+To be able to log in to NetBox, you can create a super user with the next command:
+
+```bash
+juju run netbox/0 create-superuser username=admin [email protected]
 ```
 
-Congratulations, With the username created and the password provided in the response, 
-you have now full access to your own NetBox!
+Congratulations! Your username has been created, and the password provided in the response
+gives you full access to your NetBox. Simply visit http://netbox_hostname/netbox-tutorial-netbox
+and log in using your username and password.
+
+# Clean up the Environment
+
+Well done! You’ve successfully completed the NetBox tutorial. To remove the
+model environment you created during this tutorial, use the following command.
+
+```bash
+juju destroy-model netbox-tutorial
+```

charm/requirements-doc.txt

@@ -0,0 +1,2 @@
+myst-parser==4.0.0
+sphinx-markdown-builder==0.6.7

charm/src-docs/Makefile

@@ -0,0 +1,23 @@
+# Copyright 2024 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

charm/src-docs/conf.py

@@ -0,0 +1,33 @@
+# Copyright 2024 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'NetBox'
+copyright = '2024, Canonical'
+author = 'Canonical'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx_markdown_builder",
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

charm/src-docs/make.bat

@@ -0,0 +1,38 @@
+rem Copyright 2024 Canonical Ltd.
+rem See LICENSE file for licensing details.
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd