Add documentation about deployment

docs/conf.py

@@ -7,6 +7,9 @@
 import mxcubeweb
 
 
+MXCUBE_NAME = "MXCuBE"
+MXCUBE_CORE_NAME = f"{MXCUBE_NAME}-Web"
+MXCUBE_WEB_NAME = f"{MXCUBE_NAME}-Web"
 PROJECT_PACKAGE_NAME = "mxcubeweb"  # Distribution package (not import package)
 PROJECT_PACKAGE_METADATA = importlib.metadata.metadata(PROJECT_PACKAGE_NAME)
 
@@ -18,9 +21,7 @@
 
 # -- General configuration ------------------------------------------------
 
-extensions = [
-    "myst_parser",
-]
+extensions = []
 
 source_suffix = {
     ".rst": "restructuredtext",
@@ -29,7 +30,7 @@
 
 root_doc = "contents"
 
-project = "MXCuBE-Web"
+project = MXCUBE_WEB_NAME
 author = PROJECT_PACKAGE_METADATA["Author"]
 copyright = f"{datetime.datetime.today().year}, {author}"
 
@@ -40,6 +41,9 @@
 release = version
 
 rst_prolog = f"""
+.. |mxcube| replace:: {MXCUBE_NAME}
+.. |mxcubecore| replace:: {MXCUBE_CORE_NAME}
+.. |mxcubeweb| replace:: {MXCUBE_WEB_NAME}
 .. |project| replace:: {project}
 """
 
@@ -51,6 +55,21 @@
 
 # -- Extensions ---------------------------------------------------------------
 
+# -- myst_parser
+# https://myst-parser.readthedocs.io
+
+extensions.append("myst_parser")
+
+myst_enable_extensions = ("substitution",)
+
+myst_substitutions = {
+    "mxcube": MXCUBE_NAME,
+    "mxcubecore": MXCUBE_CORE_NAME,
+    "mxcubeweb": MXCUBE_WEB_NAME,
+    "project": project,
+}
+
+
 # -- sphinx.ext.autodoc
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 

docs/source/dev/deployment.md

@@ -0,0 +1,69 @@
+# Deployment
+
+Some aspects to pay attention to
+when considering the deployment of {{ project }} into a production environment.
+
+
+## Python backend part of the web application
+
+The Python backend part of {{ project }}
+uses [*Poetry*](https://python-poetry.org/) as development workflow tool.
+One of Poetry's features is support for a so-called *lockfile*.
+Poetry's lockfile is the `poetry.lock` file
+one can see at the root of the source code tree of {{ project }}.
+
+This lockfile helps create repeatable installations.
+By taking advantage of Poetry's lockfile
+it should be possible to minimize the chances of dependency issues from happening.
+Indeed, the lockfile contains pinned versions of the dependencies
+along with some info about the dependency artefacts to be installed
+and some additional metadata.
+
+By using a command like `poetry install`,
+it is ensured that the dependency versions installed are well known,
+and for example that they are the ones used during development phase
+and during automated tests.
+
+
+### Install without using Poetry
+
+Poetry is a tool meant for development, it is not an installer, like *pip* for example.
+It is debatable whether it is a good idea to use Poetry's `poetry install` command
+to install and deploy in a production environment.
+Some might prefer to use a dedicated installer tool, like pip for such a task.
+
+But Poetry's lockfile format is not standardized, its content is specific to Poetry.
+So this file is not immediately usable by other installers and tools.
+
+To circumvent this, one could use a command like `poetry export`
+to generate a `requirements.txt` file compatible with pip (and some other tools).
+With a series of commands like the following,
+it should be possible to approximate the behaviour of installing with Poetry's lockfile.
+
+1. Let Poetry export its lockfile into a pip-compatible requirements file
+    ```shell
+    poetry export --format=requirements.txt > requirements.txt
+    ```
+
+1. Move the `requirements.txt` file to the deployment target system
+
+1. On the deployment system, let pip install {{project}} via the exported requirements file
+
+    1. Install the dependencies
+        ```shell
+        python -m pip install --requirement requirements.txt
+        ```
+
+    1. Install {{project}} itself,
+        and make sure to skip the dependencies (with the `--no-deps` flag)
+        since they are now already installed
+
+        * For example as editable
+          ```shell
+          python -m pip install --no-deps --editable mxcubeweb
+          ```
+
+        * Or not
+          ```shell
+          python -m pip install --no-deps mxcubeweb
+          ```

docs/source/dev/index.rst

@@ -4,7 +4,6 @@ Developer documentation
 
 .. toctree::
     :caption: Contents:
-    :glob:
     :maxdepth: 2
     :titlesonly:
 
@@ -16,3 +15,4 @@ Developer documentation
     login.rst
     sample-changer-changes-and-maintenance.md
     tutorial.md
+    deployment.md