launchpad-reviewers team mailing list archive

[Colin Watson <mp+440622@xxxxxxxxxxxxxxxxxx>]

Colin Watson has proposed merging ~cjwatson/lp-archive:doc-deployment into lp-archive:main.

Commit message:
Add deployment documentation

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~cjwatson/lp-archive/+git/lp-archive/+merge/440622

Historically we've put this sort of thing in our internal wiki, but let's start having it alongside the service code where it's easier to find.

This also includes Sphinx setup.
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~cjwatson/lp-archive:doc-deployment into lp-archive:main.

diff --git a/.gitignore b/.gitignore
index 2c2f17b..5d7d5f5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,4 @@
 /version-info.txt
 /wheels
 __pycache__
+docs/_build/
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..eed32c7
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,61 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "lp-archive"
+copyright = "2022-2023, Canonical Ltd"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    "**": [
+        "globaltoc.html",
+        "relations.html",  # needs 'show_related': True theme option to display
+        "searchbox.html",
+    ]
+}
diff --git a/docs/how-to/deployment.rst b/docs/how-to/deployment.rst
new file mode 100644
index 0000000..ae7d608
--- /dev/null
+++ b/docs/how-to/deployment.rst
@@ -0,0 +1,93 @@
+Deploying lp-archive
+====================
+
+The dogfood and production instances of ``lp-archive`` are deployed in PS5.
+Each instance has its own management environment:
+
++------------+----------------------------------------------------------+
+| Instance   | Management environment                                   |
++============+==========================================================+
+| production | ``prod-launchpad-archive@is-bastion-ps5.internal``       |
++------------+----------------------------------------------------------+
+| dogfood    | ``stg-launchpad-archive@launchpad-bastion-ps5.internal`` |
++------------+----------------------------------------------------------+
+
+Both instances are deployed by developers using `Mojo
+<https://mojo.canonical.com/>`_.  The dogfood instance is managed by us
+directly, including the ability to ``juju ssh`` to units and inspect them.
+The production instance is managed by IS and we don't have direct access to
+units (since they have business-critical uptime requirements), but we have
+an SSH trigger by which we can run ordinary upgrade operations.
+
+These instructions are directed at developers who already have suitable
+access, which is controlled using `Terraform
+<https://git.launchpad.net/canonical-terraform-plans/tree/prodstack/ps5/environments/launchpad/staging/main.tf>`_.
+
+The deployed machines are controlled by a combination of the `lp-archive
+charm <https://git.launchpad.net/lp-archive/tree/charm/lp-archive>`_ (built
+by a `recipe
+<https://launchpad.net/~launchpad/lp-archive/+charm/lp-archive>`_ on
+Launchpad) and configuration in the `Juju bundle
+<https://git.launchpad.net/launchpad-mojo-specs/tree/lp-archive/bundle.yaml>`_.
+
+`Deployable <https://deployable.ols.canonical.com/project/lp-archive>`_ is
+used to track QA.  The `history of the Mojo spec
+<https://git.launchpad.net/launchpad-mojo-specs/log/lp-archive>`_ serves as
+a log of changes.
+
+Deploying to dogfood
+--------------------
+
+#. Check that the commit you want to deploy has had a deployment artifact
+   built by the corresponding `build job
+   <https://jenkins.ols.canonical.com/online-services/job/lp-archive-build-charm/>`_.
+   (This normally happens quite soon after the commit lands on the ``main``
+   branch.)
+
+#. Update the `bundle
+   <https://git.launchpad.net/launchpad-mojo-specs/tree/lp-archive/bundle.yaml>`_.
+
+   * If you need to upgrade the code, set ``build_label``.
+
+   * If you need to upgrade the charm, use ``juju info lp-archive`` to check
+     what charm revisions are available, and set ``revision`` to the
+     appropriate one (usually the latest).
+
+   * Include any fixed bugs in your commit message.
+
+   * If you're only making changes of this form, then you can push them
+     directly without needing a merge proposal.
+
+#. As ``stg-launchpad-archive@launchpad-bastion-ps5.internal``, run ``mojo
+   run``.
+
+#. Check the behaviour of https://snapshot.dogfood.content.paddev.net/ and
+   https://snapshot.ppa.dogfood.content.paddev.net/ as appropriate.
+
+Deploying to production
+-----------------------
+
+#. Ensure that you have deployed the same changes to dogfood first, as
+   above.
+
+#. Create a deployment request for the desired commit on `deployable
+   <https://deployable.ols.canonical.com/project/lp-archive>`_.
+
+#. As ``stg-launchpad-archive@launchpad-bastion-ps5.internal``, run ``ssh
+   prod-launchpad-archive@is-bastion-ps5.internal autodeploy-trigger
+   prod-launchpad-archive``.
+
+#. Check the behaviour of https://snapshot.ubuntu.com/ and
+   https://snapshot.ppa.launchpad.net/ as appropriate.
+
+#. Change the status of any fixed bugs to "Fix Released".  (Note that fixing
+   some bugs may be a multi-step process, so check whether they're really
+   done first.)
+
+#. Mark the deployment request on `deployable
+   <https://deployable.ols.canonical.com/project/lp-archive>`_ as deployed.
+   (This has the effect of removing the deployed commits from the deployment
+   queue.)
+
+#. Ensure that `bugs <https://bugs.launchpad.net/lp-archive>`_ are filed for
+   any deployment issues.
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..341983c
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,14 @@
+.. include:: ../README.rst
+
+.. toctree::
+   :hidden:
+
+   Home <self>
+
+How-to guides
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   how-to/deployment
diff --git a/setup.cfg b/setup.cfg
index 104d3ee..cae7361 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -28,6 +28,8 @@ install_requires =
 python_requires = >=3.10
 
 [options.extras_require]
+docs =
+    sphinx
 test =
     coverage
     pytest
diff --git a/tox.ini b/tox.ini
index ce949ce..8db697a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -72,3 +72,12 @@ commands =
     coverage run -m pytest tests
     coverage html
     coverage report -m  --fail-under=100
+
+[testenv:docs]
+description =
+    generate documentation
+basepython =
+    python3.10
+extras = docs
+commands =
+    sphinx-build -W -b html -d docs/_build/doctrees docs docs/_build/html