fix/improve wsgi deployment

4 files changed, 70 insertions, 9 deletions

diff --git a/doc/examples/hydrilla.example.com.conf b/doc/examples/hydrilla.example.com.conf
index 7a78eea..c1450f1 100644
--- a/doc/examples/hydrilla.example.com.conf
+++ b/doc/examples/hydrilla.example.com.conf
@@ -10,6 +10,8 @@
 # /etc/apache2/sites-available/ or similar. Then, enable it using the following
 # command:
 #    a2ensite hydrilla.example.com
+# You also need to install and enable the wsgi module for Apache if you haven't
+# already (e.g. with libapache2-mod-wsgi-py3 Debian package).
 # The new configuration will only take effect after you restart/reload Apache2
 # daemon.
 
@@ -29,17 +31,43 @@
   DocumentRoot /var/lib/hydrilla/malcontent
 
   <Directory /var/lib/hydrilla/malcontent >
-    Require all granted
+    <IfVersion < 2.4>
+      Order allow,deny
+      Allow from all
+    </IfVersion>
+    <IfVersion >= 2.4>
+      Require all granted
+    </IfVersion>
   </Directory>
 
   <Directory ~ "^/var/lib/hydrilla/malcontent/(resource|mapping)/" >
     ForceType application/json
   </Directory>
 
+  # Make Apache2 automatically pick up the new version of the wsgi script when
+  # it gets written. This line will fail if you don't have mod_wsgi installed
+  # and enabled.
   WSGIScriptReloading On
 
+  # The default configuration of mod_wsgi on most *nix systems is to run wsgi
+  # scripts in so-called embedded mode. The following 2 lines instruct Apache to
+  # instead run our wsgi script in a daemon process which makes it more flexible
+  # and reliable. Here we also set environment variables that are needed to tell
+  # Python that the system supports UTF-8 encoding.
+  # Feel free to modify the arguments to WSGIDaemonProcess according to your
+  # needs:
+  # https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html#delegation-to-daemon-process
+  WSGIDaemonProcess hydrilla.example.com lang='C.UTF-8' locale='C.UTF-8'
+  WSGIProcessGroup hydrilla.example.com
+
   <Directory /var/lib/hydrilla/wsgi >
-    Require all granted
+    <IfVersion < 2.4>
+      Order allow,deny
+      Allow from all
+    </IfVersion>
+    <IfVersion >= 2.4>
+      Require all granted
+    </IfVersion>
   </Directory>
 
   WSGIScriptAliasMatch "^/((resource|mapping)/[^/]+[.]json|query)$" "/var/lib/hydrilla/wsgi/hydrilla.wsgi/$1"
diff --git a/doc/examples/hydrilla.example.com.tls.conf b/doc/examples/hydrilla.example.com.tls.conf
index e9d241f..357ecb3 100644
--- a/doc/examples/hydrilla.example.com.tls.conf
+++ b/doc/examples/hydrilla.example.com.tls.conf
@@ -10,6 +10,8 @@
 # /etc/apache2/sites-available/ or similar. Then, enable it using the following
 # command:
 #    a2ensite hydrilla.example.com.tls
+# You also need to install and enable the wsgi module for Apache if you haven't
+# already (e.g. with libapache2-mod-wsgi-py3 Debian package).
 # The new configuration will only take effect after you restart/reload Apache2
 # daemon.
 
@@ -39,17 +41,43 @@
     DocumentRoot /var/lib/hydrilla/malcontent
 
     <Directory /var/lib/hydrilla/malcontent >
-      Require all granted
+      <IfVersion < 2.4>
+        Order allow,deny
+        Allow from all
+      </IfVersion>
+      <IfVersion >= 2.4>
+        Require all granted
+      </IfVersion>
     </Directory>
 
     <Directory ~ "^/var/lib/hydrilla/malcontent/(resource|mapping)/" >
       ForceType application/json
     </Directory>
 
+    # Make Apache2 automatically pick up the new version of the wsgi script when
+    # it gets written. This line will fail if you don't have mod_wsgi installed
+    # and enabled.
     WSGIScriptReloading On
 
+    # The default configuration of mod_wsgi on most *nix systems is to run wsgi
+    # scripts in so-called embedded mode. The following 2 lines instruct Apache
+    # to instead run our wsgi script in a daemon process which makes it more
+    # flexible and reliable. Here we also set environment variables that are
+    # needed to tell Python that the system supports UTF-8 encoding.
+    # Feel free to modify the arguments to WSGIDaemonProcess according to your
+    # needs:
+    # https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html#delegation-to-daemon-process
+    WSGIDaemonProcess hydrilla.example.com lang='C.UTF-8' locale='C.UTF-8'
+    WSGIProcessGroup hydrilla.example.com
+
     <Directory /var/lib/hydrilla/wsgi >
-      Require all granted
+      <IfVersion < 2.4>
+        Order allow,deny
+        Allow from all
+      </IfVersion>
+      <IfVersion >= 2.4>
+        Require all granted
+      </IfVersion>
     </Directory>
 
     WSGIScriptAliasMatch "^/((resource|mapping)/[^/]+[.]json|query)$" "/var/lib/hydrilla/wsgi/hydrilla.wsgi/$1"
@@ -57,6 +85,7 @@
     ErrorLog ${APACHE_LOG_DIR}/error.log
     CustomLog ${APACHE_LOG_DIR}/access.log combined
 
+    # Change the paths to point to your actual certificate files.
     SSLEngine on
     SSLCertificateFile          /etc/letsencrypt/live/example.com/cert.pem
     SSLCertificateKeyFile       /etc/letsencrypt/live/example.com/privkey.pem
diff --git a/doc/examples/hydrilla.wsgi b/doc/examples/hydrilla.wsgi
index 3455701..70dd895 100644
--- a/doc/examples/hydrilla.wsgi
+++ b/doc/examples/hydrilla.wsgi
@@ -18,9 +18,10 @@ from hydrilla.server import start_wsgi
 # The following line will initialize Hydrilla with the default, internal
 # configuration while also attempting to load /etc/hydrilla/config.json if it's
 # present.
-application = start_wsgi()
+application = start_wsgi(standalone_mode=False)
 
 # Comment the above and uncomment this to use a different config file.
 
 #from hydrilla.server import config
-#application = start_wsgi(config.load(['/path/to/config.json']))
+#application = start_wsgi(standalone_mode=False,
+#                         obj=config.load(['/path/to/config.json']))
diff --git a/src/hydrilla/server/serve.py b/src/hydrilla/server/serve.py
index d2835f6..d07d44f 100644
--- a/src/hydrilla/server/serve.py
+++ b/src/hydrilla/server/serve.py
@@ -625,10 +625,13 @@ start = click.command()(start)
 @click.version_option(version=_version.version, prog_name='Hydrilla',
                       message=_('%(prog)s_%(version)s_license'),
                       help=_('version_printing'))
-def start_wsgi(_config=None) -> None:
+def start_wsgi() -> None:
     """<this will be replaced by a localized docstring for Click to pick up>"""
-    return HydrillaApp(_config or config.load())
+    return HydrillaApp(click.get_current_context().obj or config.load())
 
 start_wsgi.__doc__ = _('serve_hydrilla_packages_wsgi_help')
 
-start_wsgi = click.command()(start_wsgi)
+start_wsgi = click.command(context_settings={
+    'ignore_unknown_options': True,
+    'allow_extra_args': True
+})(start_wsgi)