diff --git a/docs/en_US/server_deployment.rst b/docs/en_US/server_deployment.rst index afb8a5adffa..4c5c70e3999 100644 --- a/docs/en_US/server_deployment.rst +++ b/docs/en_US/server_deployment.rst @@ -305,6 +305,126 @@ Then, configure NGINX: uwsgi_pass unix:/tmp/pgadmin4.sock; } +Caddy Configuration with Gunicorn +---------------------------------- + +pgAdmin can be hosted by Gunicorn, with Caddy in front of it as a reverse +proxy. Note that these examples assume pgAdmin was installed using the Python +Wheel (you may need to adjust the path to suit your installation). + +To run with pgAdmin in the root directory of the server, start Gunicorn using +a command similar to: + +.. code-block:: bash + + gunicorn --bind unix:/tmp/pgadmin4.sock \ + --workers=1 \ + --threads=25 \ + --chdir /usr/lib/python3.7/dist-packages/pgadmin4 \ + pgAdmin4:app + +And configure Caddy: + +.. code-block:: text + + pgadmin.example.com { + reverse_proxy unix//tmp/pgadmin4.sock + } + +Alternatively, pgAdmin can be hosted in a sub-directory (/pgadmin4 in this +case) on the server. Start Gunicorn as when using the root directory, but +also set the ``SCRIPT_NAME`` environment variable for the Gunicorn process, +so that pgAdmin knows to generate URLs, redirects (including the one issued +after a successful login) and session cookies relative to the sub-directory, +rather than to the root of the server: + +.. code-block:: bash + + SCRIPT_NAME=/pgadmin4 gunicorn --bind unix:/tmp/pgadmin4.sock \ + --workers=1 \ + --threads=25 \ + --chdir /usr/lib/python3.7/dist-packages/pgadmin4 \ + pgAdmin4:app + +Then configure Caddy. The request path must be passed through to Gunicorn +unchanged, so do not strip the /pgadmin4 prefix; a custom ``X-Script-Name`` +header must be set so that pgAdmin can identify requests made under the +sub-directory; and the path matcher must include both ``/pgadmin4`` and +``/pgadmin4/*``, so that pgAdmin's own redirect to the bare sub-directory +path (with no trailing slash) is also proxied, rather than falling through +to Caddy's default (and rather unhelpful) empty response for an unmatched +path: + +.. code-block:: text + + pgadmin.example.com { + @pgadmin path /pgadmin4 /pgadmin4/* + handle @pgadmin { + reverse_proxy unix//tmp/pgadmin4.sock { + header_up X-Script-Name /pgadmin4 + } + } + } + +Caddy Configuration with uWSGI +------------------------------- + +Caddy does not speak the native uwsgi protocol used by NGINX's +``uwsgi_pass``, so uWSGI must be run in HTTP mode instead, using +``--http-socket`` rather than ``--socket``. Note that these examples assume +pgAdmin was installed using the Python Wheel (you may need to adjust the +path to suit your installation). + +To run with pgAdmin in the root directory of the server, start uWSGI using a +command similar to: + +.. code-block:: bash + + uwsgi --http-socket /tmp/pgadmin4.sock \ + --processes 1 \ + --threads 25 \ + --chdir /usr/lib/python3.7/dist-packages/pgadmin4/ \ + --mount /=pgAdmin4:app + +And configure Caddy: + +.. code-block:: text + + pgadmin.example.com { + reverse_proxy unix//tmp/pgadmin4.sock + } + +Alternatively, pgAdmin can be hosted in a sub-directory (/pgadmin4 in this +case) on the server. Start uWSGI, noting that the directory name is specified +in the ``mount`` parameter, and that the ``SCRIPT_NAME`` environment variable +is still required alongside it. ``--manage-script-name`` only affects the +per-request WSGI environment that uWSGI builds; it does not set pgAdmin's +``APPLICATION_ROOT``, which is read once from the process environment at +startup and used for, amongst other things, the redirect issued after a +successful login: + +.. code-block:: bash + + SCRIPT_NAME=/pgadmin4 uwsgi --http-socket /tmp/pgadmin4.sock \ + --processes 1 \ + --threads 25 \ + --chdir /usr/lib/python3.7/dist-packages/pgadmin4/ \ + --manage-script-name \ + --mount /pgadmin4=pgAdmin4:app + +Then configure Caddy exactly as for the Gunicorn sub-directory example above: + +.. code-block:: text + + pgadmin.example.com { + @pgadmin path /pgadmin4 /pgadmin4/* + handle @pgadmin { + reverse_proxy unix//tmp/pgadmin4.sock { + header_up X-Script-Name /pgadmin4 + } + } + } + Additional Information ----------------------