chore: comments say what the code does

- gunicorn.conf.py was gunicorn's sample file: pages of generic
  comments, a broken link and examples of the eventlet worker the panel
  no longer has. Only the panel's own comments stay; every setting keeps
  its value.
- docker-compose.yml: the backups hold the database, keys and
  certificates, not "both".
- accounts' system checks point to settings.py.template, which has the
  middleware they ask for (the README does not list it).
- The authorization matrix test names doc/permissions.md, where the
  roles table is; the keymap list no longer cites a dead page.

accounts/checks.py

@@ -14,7 +14,7 @@ def password_change_middleware_check(app_configs, **kwargs):
         return [
             Error(
                 "ForcePasswordChangeMiddleware must follow AuthenticationMiddleware.",
-                hint=f"Add '{required}' to MIDDLEWARE in webvirtcloud/settings.py; see README.md.",
+                hint=f"Add '{required}' to MIDDLEWARE in webvirtcloud/settings.py, as settings.py.template does.",
                 id="accounts.E001",
             )
         ]
@@ -31,7 +31,7 @@ def login_required_middleware_check(app_configs, **kwargs):
             Error(
                 "MIDDLEWARE must use Django's LoginRequiredMiddleware.",
                 hint=f"In webvirtcloud/settings.py replace '{old}' with '{required}' "
-                "and delete LOGIN_REQUIRED_IGNORE_VIEW_NAMES; see README.md.",
+                "and delete LOGIN_REQUIRED_IGNORE_VIEW_NAMES, as settings.py.template does.",
                 id="accounts.E002",
             )
         ]

docker-compose.yml

@@ -39,7 +39,7 @@ services:
       - webvirtcloud-ssh:/var/www/.ssh
       # Persistent TLS client certificates for TLS computes (.pki/libvirt)
       - webvirtcloud-pki:/var/www/.pki
-      # Daily backups of both (manage.py backup)
+      # Daily backups of the database, keys and certificates (manage.py backup)
       - webvirtcloud-backups:/srv/webvirtcloud/backups
 
 volumes:

gunicorn.conf.py

@@ -1,81 +1,14 @@
+"""gunicorn's settings for the panel (systemd and Docker run it with -c)."""
+
 import os
 
-# Sample Gunicorn configuration file.
-
-#
-# Server socket
-#
-# bind - The socket to bind.
-#
-#       A string of the form: 'HOST', 'HOST:PORT', 'unix:PATH'.
-#       An IP is a valid HOST.
-#
-#   backlog - The number of pending connections. This refers
-#       to the number of clients that can be waiting to be
-#       served. Exceeding this number results in the client
-#       getting an error when attempting to connect. It should
-#       only affect servers under significant load.
-#
-#       Must be a positive integer. Generally set in the 64-2048
-#       range.
-#
-
-# bind = 'unix:/srv/webvirtcloud/venv/wvcloud.socket'
+# behind nginx, on the loopback only
 bind = '127.0.0.1:8000'
 backlog = 2048
 
-#
-# Worker processes
-#
-#   workers - The number of worker processes that this server
-#       should keep alive for handling requests.
-#
-#       A positive integer generally in the 2-4 x $(NUM_CORES)
-#       range. You'll want to vary this a bit to find the best
-#       for your particular application's work load.
-#
-#   worker_class - The type of workers to use. The default
-#       async class should handle most 'normal' types of work
-#       loads. You'll want to read http://gunicorn/deployment.hml
-#       for information on when you might want to choose one
-#       of the other worker classes.
-#
-#       An string referring to a 'gunicorn.workers' entry point
-#       or a python path to a subclass of
-#       gunicorn.workers.base.Worker. The default provided values
-#       are:
-#
-#           egg:gunicorn#sync
-#           egg:gunicorn#eventlet   - Requires eventlet >= 0.9.7
-#           egg:gunicorn#gevent     - Requires gevent >= 0.12.2 (?)
-#           egg:gunicorn#tornado    - Requires tornado >= 0.2
-#
-#   worker_connections - For the eventlet and gevent worker classes
-#       this limits the maximum number of simultaneous clients that
-#       a single process can handle.
-#
-#       A positive integer generally set to around 1000.
-#
-#   timeout - If a worker does not notify the master process in this
-#       number of seconds it is killed and a new worker is spawned
-#       to replace it.
-#
-#       Generally set to thirty seconds. Only set this noticeably
-#       higher if you're sure of the repercussions for sync workers.
-#       For the non sync workers it just means that the worker
-#       process is still communicating and is not tied to the length
-#       of time required to handle a single request.
-#
-#   keepalive - The number of seconds to wait for the next request
-#       on a Keep-Alive HTTP connection.
-#
-#       A positive integer. Generally set in the 1-5 seconds range.
-#
-
-
-# Sync workers, each holding its own libvirt connections and blocking for a
-# whole long operation; capped so a big host does not start dozens of them
-# against sqlite. Override with GUNICORN_CMD_ARGS="--workers N".
+# Workers, each holding its own libvirt connections; capped so a big host
+# does not start dozens of them against sqlite. Override with
+# GUNICORN_CMD_ARGS="--workers N".
 MAX_WORKERS = 8
 
 
@@ -98,64 +31,9 @@ keepalive = 0
 # gunicorn 26's control socket is unused, and the service user cannot create it
 control_socket_disable = True
 
-#
-# Debugging
-#
-#   debug - Turn on debugging in the server. This limits the number of
-#       worker processes to 1 and changes some error handling that's
-#       sent to clients.
-#
-#       True or False
-#
-#   spew - Install a trace function that spews every line of Python
-#       that is executed when running the server. This is the
-#       nuclear option.
-#
-#       True or False
-#
-
 debug = False
 spew = False
 
-#
-# Server mechanics
-#
-#   daemon - Detach the main Gunicorn process from the controlling
-#       terminal with a standard fork/fork sequence.
-#
-#       True or False
-#
-#   pidfile - The path to a pid file to write
-#
-#       A path string or None to not write a pid file.
-#
-#   user - Switch worker processes to run as this user.
-#
-#       A valid user id (as an integer) or the name of a user that
-#       can be retrieved with a call to pwd.getpwnam(value) or None
-#       to not change the worker process user.
-#
-#   group - Switch worker process to run as this group.
-#
-#       A valid group id (as an integer) or the name of a user that
-#       can be retrieved with a call to pwd.getgrnam(value) or None
-#       to change the worker processes group.
-#
-#   umask - A mask for file permissions written by Gunicorn. Note that
-#       this affects unix socket permissions.
-#
-#       A valid value for the os.umask(mode) call or a string
-#       compatible with int(value, 0) (0 means Python guesses
-#       the base, so values like "0", "0xFF", "0022" are valid
-#       for decimal, hex, and octal representations)
-#
-#   tmp_upload_dir - A directory to store temporary request data when
-#       requests are read. This will most likely be disappearing soon.
-#
-#       A path to a directory where the process owner can write. Or
-#       None to signal that Python should choose one on its own.
-#
-
 daemon = False
 pidfile = None
 umask = 0
@@ -163,18 +41,7 @@ user = None
 group = None
 tmp_upload_dir = None
 
-#
-#   Logging
-#
-#   logfile - The path to a log file to write to.
-#
-#       A path string. "-" means log to stdout.
-#
-#   loglevel - The granularity of log output
-#
-#       A string of "debug", "info", "warning", "error", "critical"
-#
-
+# to the service's output: the journal, or docker logs
 logfile = '-'
 loglevel = 'info'
 accesslog = '-'
@@ -182,44 +49,4 @@ accesslog = '-'
 # request's ID, as on the app log's lines
 access_log_format = '%({x-real-ip}i)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %({x-request-id}o)s'
 
-#
-# Process naming
-#
-#   proc_name - A base to use with setproctitle to change the way
-#       that Gunicorn processes are reported in the system process
-#       table. This affects things like 'ps' and 'top'. If you're
-#       going to be running more than one instance of Gunicorn you'll
-#       probably want to set a name to tell them apart. This requires
-#       that you install the setproctitle module.
-#
-#       A string or None to choose a default of something like 'gunicorn'.
-#
-
 proc_name = None
-
-#
-# Server hooks
-#
-#   post_fork - Called just after a worker has been forked.
-#
-#       A callable that takes a server and worker instance
-#       as arguments.
-#
-#   pre_fork - Called just prior to forking the worker subprocess.
-#
-#       A callable that accepts the same arguments as after_fork
-#
-#   pre_exec - Called just prior to forking off a secondary
-#       master process during things like config reloading.
-#
-#       A callable that takes a server instance as the sole argument.
-#
-#
-# def post_fork(server, worker):
-#     pass
-#
-# def pre_fork(server, worker):
-#     pass
-#
-# def pre_exec(server):
-#     pass

webvirtcloud/settings.py.template

@@ -320,7 +320,7 @@ QEMU_CONSOLE_LISTENER_ADDRESSES = (
     ("0.0.0.0", _("All interfaces")),
 )
 
-# List taken from http://qemu.weilnetz.de/qemu-doc.html#sec_005finvocation
+# the keymaps of QEMU's -k option
 QEMU_KEYMAPS = [
     "ar",
     "da",

webvirtcloud/tests/test_authorization_matrix.py

@@ -79,7 +79,7 @@ DENIED = (403, 404)
 
 # Per-role reachability on the test VM, outside ALLOWED_FOR_ANY_USER. Compared
 # in both directions: an extra URL is a privilege leak, a missing one is a
-# regression. Must match the roles table in README.md.
+# regression. Must match the roles table in doc/permissions.md.
 VIEW_VM = {
     "instances:instance",
     "instances:status",