From 5a2f429debd549aac457006a51d50cca88405ab9 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephen@that.guru>
Date: Sat, 20 Feb 2021 16:07:02 +0000
Subject: docs: Refresh the guide for Ubuntu 20.04

Nothing changes wrt package names, which is nice. We take the
opportunity to clarify some wording, however.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 docs/deployment/installation.rst         | 45 +++++++++++++++++++++++---------
 lib/uwsgi/patchwork.ini                  | 10 +++++--
 patchwork/settings/production.example.py |  6 +----
 3 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/docs/deployment/installation.rst b/docs/deployment/installation.rst
index e6eb350..1abf187 100644
--- a/docs/deployment/installation.rst
+++ b/docs/deployment/installation.rst
@@ -41,7 +41,7 @@ providers don't support. We address this in the appropriate section below.
 Requirements
 ------------
 
-For the purpose of this guide, we will assume an **Ubuntu 18.04** host:
+For the purpose of this guide, we will assume an **Ubuntu 20.04** host:
 commands, package names and/or package versions will likely change if using a
 different distro or release. Similarly, usage of different package versions to
 the ones suggested may require slightly different configuration.
@@ -155,7 +155,7 @@ We will install this under ``/opt``, though this is only a suggestion:
 .. code-block:: shell
 
    $ tar -xvzf v3.0.0.tar.gz
-   $ sudo mv v3.0.0 /opt/patchwork
+   $ sudo mv patchwork-3.0.0 /opt/patchwork
 
 .. important::
 
@@ -233,7 +233,8 @@ As a reminder, these were:
 - ``DATABASE_HOST``
 - ``DATABASE_PORT``
 
-Configure the ``DATABASE`` setting in ``production.py`` accordingly.
+Export these environment variables or configure the ``DATABASE`` setting in
+``production.py`` accordingly.
 
 Static Files
 ^^^^^^^^^^^^
@@ -246,8 +247,8 @@ location that these files will be stored in. We will install these under
 
    $ sudo mkdir -p /var/www/patchwork
 
-You can configure this by configuring the ``STATIC_ROOT`` setting in
-``production.py``.
+Export the ``STATIC_ROOT`` environment variable or configure the
+``STATIC_ROOT`` setting in ``production.py``.
 
 .. code-block:: python
 
@@ -263,16 +264,13 @@ This should be a random value and kept secret. You can generate and a value for
 .. code-block:: python
 
    import string
-   try:
-       import secrets
-   except ImportError:  # Python < 3.6
-       import random
-       secrets = random.SystemRandom()
+   import secrets
 
    chars = string.ascii_letters + string.digits + string.punctuation
    print("".join([secrets.choice(chars) for i in range(50)]))
 
-Once again, store this in ``production.py``.
+Export the ``DJANGO_STATIC_KEY`` environment variable or configure the
+``STATIC_KEY`` setting in ``production.py``.
 
 Other Options
 ^^^^^^^^^^^^^
@@ -280,7 +278,6 @@ Other Options
 There are many other settings that may be configured, many of which are
 described in :doc:`configuration`.
 
-* ``SECRET_KEY``
 * ``ADMINS``
 * ``TIME_ZONE``
 * ``LANGUAGE_CODE``
@@ -315,6 +312,24 @@ Once done, we should be able to check that all requirements are met using the
 
    $ sudo -u www-data python3 manage.py check
 
+.. note::
+
+   If you've been using environment variables to configure your deployment,
+   you must pass the ``--preserve-env`` option for each attribute or pass the
+   environments as part of the command:
+
+   .. code-block:: shell
+
+      $ sudo -u www-data \
+          --preserve-env=DATABASE_NAME \
+          --preserve-env=DATABASE_USER \
+          --preserve-env=DATABASE_PASS \
+          --preserve-env=DATABASE_HOST \
+          --preserve-env=DATABASE_PORT \
+          --preserve-env=STATIC_ROOT \
+          --preserve-env=DJANGO_SECRET_KEY \
+      python3 manage.py check
+
 We should also take this opportunity to both configure the database and static
 files:
 
@@ -406,6 +421,12 @@ Now, use the provided configuration for *uWSGI*:
    We created the ``/etc/uwsgi`` directory above because we're going to run
    *uWSGI* in `emperor mode`__. This has benefits for multi-app deployments.
 
+.. note::
+
+   If you're using environment variables for configuration, you will need to
+   edit the ``patchwork.ini`` file created above to include these using the
+   ``env = VAR=VALUE`` syntax.
+
 __ https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html
 
 Configure Patchwork
diff --git a/lib/uwsgi/patchwork.ini b/lib/uwsgi/patchwork.ini
index 39ffbd6..95a0613 100644
--- a/lib/uwsgi/patchwork.ini
+++ b/lib/uwsgi/patchwork.ini
@@ -1,6 +1,4 @@
 [uwsgi]
-
-# change this to python27 if running Patchwork under Python 2.7
 plugins = python3
 
 project = patchwork
@@ -9,6 +7,14 @@ user = www-data
 group = www-data
 url = /
 
+# env = DJANGO_SECRET_KEY=
+# env = DATABASE_NAME=
+# env = DATABASE_USER=
+# env = DATABASE_PASS=
+# env = DATABASE_HOST=
+# env = DATABASE_PORT=
+# env = STATIC_ROOT=
+
 chdir = %(base)/%(project)
 pythonpath = %(base)/%(project)
 module = %(project).wsgi:application
diff --git a/patchwork/settings/production.example.py b/patchwork/settings/production.example.py
index d51dcdd..caaf429 100644
--- a/patchwork/settings/production.example.py
+++ b/patchwork/settings/production.example.py
@@ -22,11 +22,7 @@ from .base import *  # noqa
 # be used to generate a secret key:
 #
 #      import string
-#      try:
-#          import secrets
-#      except ImportError:  # Python < 3.6
-#          import random
-#          secrets = random.SystemRandom()
+#      import secrets
 #
 #      chars = string.ascii_letters + string.digits + string.punctuation
 #      print("".join([secrets.choice(chars) for i in range(50)]))
-- 
cgit v1.2.3