docs: update 12-factor tutorials (#2085)

Update the 12-factor tutorials. Specific updates: - Convert to reStructuredText - Incorporate feedback from UX session with Daniele - Update all tutorials for consistency (feedback from previous PRs, feedback from Daniele) --------- Co-authored-by: Alex Lowe <[email protected]> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: Michael DuBelko <[email protected]>
canonical · Feb 19, 2025 · 79fa5ad · 79fa5ad
1 parent 8762f53
commit 79fa5ad
Show file tree

Hide file tree

Showing 38 changed files with 3,586 additions and 1,937 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -129,6 +129,7 @@
     "common/craft-parts/reference/plugins/go_use_plugin.rst",
     "common/craft-parts/reference/plugins/uv_plugin.rst",
     # Extra non-craft-parts exclusions can be added after this comment
+    "reuse/tutorial/*"
 ]
 
 rst_epilog = """

diff --git a/docs/reuse/tutorial/setup_edge.rst b/docs/reuse/tutorial/setup_edge.rst
@@ -0,0 +1,92 @@
+.. warning::
+
+    This tutorial requires version ``3.2.0`` or later of Charmcraft.
+    Check the version of Charmcraft using ``charmcraft --version``.
+
+First, install Multipass.
+
+.. seealso::
+
+    See more: `Multipass |
+    How to install Multipass <https://multipass.run/docs/install-multipass>`_
+
+Use Multipass to launch an Ubuntu VM with the name ``charm-dev``
+from the 24.04 blueprint:
+
+.. code-block:: bash
+
+    multipass launch --cpus 4 --disk 50G --memory 4G --name charm-dev 24.04
+
+Once the VM is up, open a shell into it:
+
+.. code-block:: bash
+
+    multipass shell charm-dev
+
+In order to create the rock, you need to install Rockcraft with
+classic confinement, which grants it access to the whole file system:
+
+.. code-block:: bash
+
+    sudo snap install rockcraft --classic
+
+
+LXD will be required for building the rock.
+Make sure it is installed and initialized:
+
+.. code-block:: bash
+
+    lxd --version
+    lxd init --auto
+
+
+If ``LXD`` is not installed, install it with ``sudo snap install lxd``.
+
+In order to create the charm, you'll need to install Charmcraft:
+
+.. code-block:: bash
+
+    sudo snap install charmcraft --channel latest/edge --classic
+
+
+MicroK8s is required to deploy the |12FactorApp| application on Kubernetes.
+Let's install MicroK8s using the ``1.31-strict/stable`` track:
+
+.. code::
+
+    sudo snap install microk8s --channel 1.31-strict/stable
+    sudo adduser $USER snap_microk8s
+    newgrp snap_microk8s
+
+Several MicroK8s add-ons are required for deployment:
+
+.. code-block:: bash
+
+    # Required for Juju to provide storage volumes
+    sudo microk8s enable hostpath-storage
+    # Required to host the OCI image of the application
+    sudo microk8s enable registry
+    # Required to expose the application
+    sudo microk8s enable ingress
+
+Check the status of MicroK8s:
+
+.. code-block:: bash
+
+   sudo microk8s status --wait-ready
+
+If successful, the terminal will output ``microk8s is running``
+along with a list of enabled and disabled add-ons.
+
+Juju is required to deploy the |12FactorApp| application.
+Install Juju using the ``3.6/stable`` track, and bootstrap a
+development controller:
+
+.. code::
+
+    sudo snap install juju --channel 3.6/stable
+    mkdir -p ~/.local/share
+    juju bootstrap microk8s dev-controller
+
+It could take a few minutes to download the images.
+
diff --git a/docs/reuse/tutorial/setup_stable.rst b/docs/reuse/tutorial/setup_stable.rst
@@ -1,4 +1,17 @@
-First, `install Multipass <https://multipass.run/docs/install-multipass>`_.
+.. warning::
+
+    This tutorial requires version ``3.2.0`` or later of Charmcraft. Check the
+    version of Charmcraft using ``charmcraft --version`` If you have an older
+    version of Charmcraft installed, use
+    ``sudo snap refresh charmcraft --channel latest/edge`` to get the latest
+    edge version of Charmcraft.
+
+First, install Multipass.
+
+.. seealso::
+
+    See more: `Multipass |
+    How to install Multipass <https://multipass.run/docs/install-multipass>`_
 
 Use Multipass to launch an Ubuntu VM with the name ``charm-dev``
 from the 24.04 blueprint:
@@ -13,58 +26,67 @@ Once the VM is up, open a shell into it:
 
     multipass shell charm-dev
 
-In order to create the rock, you'll need to install Rockcraft:
+In order to create the rock, you need to install Rockcraft with
+classic confinement, which grants it access to the whole file system:
 
 .. code-block:: bash
 
     sudo snap install rockcraft --classic
 
-``LXD`` will be required for building the rock.
-Make sure it is installed and initialised:
+LXD will be required for building the rock.
+Make sure it is installed and initialized:
 
 .. code-block:: bash
 
-    sudo snap install lxd
+    lxd --version
     lxd init --auto
 
+If ``LXD`` is not installed, install it with ``sudo snap install lxd``.
+
 In order to create the charm, you'll need to install Charmcraft:
 
 .. code-block:: bash
 
     sudo snap install charmcraft --channel latest/stable --classic
 
-.. warning::
-
-    This tutorial requires version ``3.0.0`` or later of Charmcraft. Check the
-    version of Charmcraft using ``charmcraft --version`` If you have an older
-    version of Charmcraft installed, use
-    ``sudo snap refresh charmcraft --channel latest/edge`` to get the latest
-    edge version of Charmcraft.
-
-MicroK8s is required to deploy the Flask application on Kubernetes. Install MicroK8s:
+MicroK8s is required to deploy the |12FactorApp| application on Kubernetes.
+Let's install MicroK8s using the ``1.31-strict/stable`` track:
 
-.. code-block:: bash
+.. code::
 
     sudo snap install microk8s --channel 1.31-strict/stable
     sudo adduser $USER snap_microk8s
     newgrp snap_microk8s
 
-Wait for MicroK8s to be ready using ``sudo microk8s status --wait-ready``.
+
 Several MicroK8s add-ons are required for deployment:
 
 .. code-block:: bash
 
+    # Required for Juju to provide storage volumes
     sudo microk8s enable hostpath-storage
-    # Required to host the OCI image of the Flask application
+    # Required to host the OCI image of the application
     sudo microk8s enable registry
-    # Required to expose the Flask application
+    # Required to expose the application
     sudo microk8s enable ingress
 
-Juju is required to deploy the Flask application.
-Install Juju and bootstrap a development controller:
+Check the status of MicroK8s:
 
 .. code-block:: bash
 
-    sudo snap install juju --channel 3.5/stable
+   sudo microk8s status --wait-ready
+
+If successful, the terminal will output ``microk8s is running``
+along with a list of enabled and disabled add-ons.
+
+Juju is required to deploy the |12FactorApp| application.
+Install Juju using the ``3.6/stable`` track, and bootstrap a
+development controller:
+
+.. code::
+
+    sudo snap install juju --channel 3.6/stable
     mkdir -p ~/.local/share
     juju bootstrap microk8s dev-controller
+
+It could take a few minutes to download the images.
diff --git a/docs/tutorial/code/django/greeting_charmcraft.yaml b/docs/tutorial/code/django/greeting_charmcraft.yaml
@@ -0,0 +1,7 @@
+config:
+  options:
+    greeting:
+      description: |
+        The greeting to be returned by the Django application.
+      default: "Hello, world!"
+      type: string
diff --git a/docs/tutorial/code/django/postgres_requires_charmcraft.yaml b/docs/tutorial/code/django/postgres_requires_charmcraft.yaml
@@ -0,0 +1,4 @@
+requires:
+  postgresql:
+    interface: postgresql_client
+    optional: false
diff --git a/docs/tutorial/code/django/requirements.txt b/docs/tutorial/code/django/requirements.txt
@@ -0,0 +1,2 @@
+Django
+psycopg2-binary
diff --git a/docs/tutorial/code/django/settings_init_rock.py b/docs/tutorial/code/django/settings_init_rock.py
@@ -0,0 +1,129 @@
+"""
+Django settings for django_hello_world project.
+
+Generated by 'django-admin startproject' using Django 5.1.4.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/5.1/topics/settings/
+
+For the full list of settings and their values, see
+https://docs.djangoproject.com/en/5.1/ref/settings/
+"""
+
+from pathlib import Path
+import json
+import os
+import secrets
+
+# Build paths inside the project like this: BASE_DIR / 'subdir'.
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+
+# Quick-start development settings - unsuitable for production
+# See https://docs.djangoproject.com/en/5.1/howto/deployment/checklist/
+
+# SECURITY WARNING: keep the secret key used in production secret!
+SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', secrets.token_hex(32))
+
+# SECURITY WARNING: don't run with debug turned on in production!
+DEBUG = os.environ.get('DJANGO_DEBUG', 'false') == 'true'
+
+ALLOWED_HOSTS = json.loads(os.environ.get('DJANGO_ALLOWED_HOSTS', '[]'))
+
+# Application definition
+
+INSTALLED_APPS = [
+    'django.contrib.admin',
+    'django.contrib.auth',
+    'django.contrib.contenttypes',
+    'django.contrib.sessions',
+    'django.contrib.messages',
+    'django.contrib.staticfiles',
+]
+
+MIDDLEWARE = [
+    'django.middleware.security.SecurityMiddleware',
+    'django.contrib.sessions.middleware.SessionMiddleware',
+    'django.middleware.common.CommonMiddleware',
+    'django.middleware.csrf.CsrfViewMiddleware',
+    'django.contrib.auth.middleware.AuthenticationMiddleware',
+    'django.contrib.messages.middleware.MessageMiddleware',
+    'django.middleware.clickjacking.XFrameOptionsMiddleware',
+]
+
+ROOT_URLCONF = 'django_hello_world.urls'
+
+TEMPLATES = [
+    {
+        'BACKEND': 'django.template.backends.django.DjangoTemplates',
+        'DIRS': [],
+        'APP_DIRS': True,
+        'OPTIONS': {
+            'context_processors': [
+                'django.template.context_processors.debug',
+                'django.template.context_processors.request',
+                'django.contrib.auth.context_processors.auth',
+                'django.contrib.messages.context_processors.messages',
+            ],
+        },
+    },
+]
+
+WSGI_APPLICATION = 'django_hello_world.wsgi.application'
+
+
+# Database
+# https://docs.djangoproject.com/en/5.1/ref/settings/#databases
+
+DATABASES = {
+    'default': {
+        'ENGINE': 'django.db.backends.postgresql',
+        'NAME': os.environ.get('POSTGRESQL_DB_NAME'),
+        'USER': os.environ.get('POSTGRESQL_DB_USERNAME'),
+        'PASSWORD': os.environ.get('POSTGRESQL_DB_PASSWORD'),
+        'HOST': os.environ.get('POSTGRESQL_DB_HOSTNAME'),
+        'PORT': os.environ.get('POSTGRESQL_DB_PORT'),
+    }
+}
+
+
+# Password validation
+# https://docs.djangoproject.com/en/5.1/ref/settings/#auth-password-validators
+
+AUTH_PASSWORD_VALIDATORS = [
+    {
+        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
+    },
+]
+
+
+# Internationalization
+# https://docs.djangoproject.com/en/5.1/topics/i18n/
+
+LANGUAGE_CODE = 'en-us'
+
+TIME_ZONE = 'UTC'
+
+USE_I18N = True
+
+USE_TZ = True
+
+
+# Static files (CSS, JavaScript, Images)
+# https://docs.djangoproject.com/en/5.1/howto/static-files/
+
+STATIC_URL = 'static/'
+
+# Default primary key field type
+# https://docs.djangoproject.com/en/5.1/ref/settings/#default-auto-field
+
+DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'