From 6fe2de01b3a7b579ca4eba791834cb7b874fad4c Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 13 Dec 2019 09:21:41 -0600 Subject: [PATCH] Mehtion SNI, Hitch, HAProxy; better wording; better markup --- README.rst | 55 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 18 deletions(-) diff --git a/README.rst b/README.rst index 28890eb..c814df9 100644 --- a/README.rst +++ b/README.rst @@ -34,23 +34,23 @@ installing PGWUI_Server is writing your own `Pyramid`_ application. PGWUI_Server stands for `PostgreSQL`_ Web User Interface, Server support. PGWUI web pages can be safely accessed by a browser running on the -local machine by installing *waitress*, a simple `WSGI`_ webserver, -alongside PGWUI_Server. PGWUI_Server provides the `WSGI`_ interface -which connects PGWUI's Python packages to any `WSGI`_ capable -webserver. +local machine by installing ``waitress``, a simple, `pip`_ +installable, `WSGI`_ webserver, alongside PGWUI_Server. PGWUI_Server +provides the `WSGI`_ interface which connects PGWUI's Python packages +to any `WSGI`_ capable webserver. Waitress is for those who want something simple and stand-alone. More -advanced users may take advantage of a more full-featured webserver -such as Apache or Nginx. Connections to PGWUI_Server can be direct, -via WSGI, or via reverse proxy to waitress or similar. +advanced users may take advantage of a more full-featured webserver or +reverse proxy like `Apache`_, `Nginx`_, `Hitch`_ or `HAProxy`_. +Connections to PGWUI_Server can be direct, via WSGI, or via reverse +proxy to waitress or similar. PGWUI_Server does not support HTTPS out-of-the-box. HTTPS is often essential for security. PGWUI_Server is designed to stand behind a reverse web proxy or an advanced WSGI web server which does support -HTTPS. Nginx, Apache, and many other full-featured web servers are -all suitable HTTPS providers. +HTTPS. -PGWUI_Server supports configuration using a traditional *.ini* file. +PGWUI_Server supports configuration using a traditional ``.ini`` file. About PGWUI @@ -85,7 +85,7 @@ Startup and Usage ----------------- PGWUI_Server comes with an example configuration which connects it to -the *waitress* `WSGI`_ webserver and configures waitress. The +the ``waitress`` `WSGI`_ webserver and configures waitress. The simplest approach is to install and use waitress as the application's WSGI server. @@ -94,7 +94,7 @@ use another WSGI capable webserver modify the appropriate sections of the supplied configuration file using the comments written into the file as a guide. -Use *pserve* to start PGWUI and the stand-alone WSGI webserver you +Use ``pserve`` to start PGWUI and the stand-alone WSGI webserver you installed:: pgwui_venv/bin/pserve /etc/pgwui.ini @@ -130,6 +130,21 @@ webserver is required to layer HTTPS with TLS encryption over PGWUI_Server's network traffic. This layering is necessary to provide privacy, identity validation, and data integrity. +A full-featured webserver or web proxy is also necessary for SNI/HTTP2 +support. + +Some popular projects providing security and other advanced webserving +features: + +`Nginx`_ + A webserver/reverse proxy with modern configuration +`Apache`_ + A traditional webserver/reverse proxy +`Hitch`_ + A lightweight reverse proxy +`HAProxy`_ + A full-featured reverse proxy + This document gives minimal guidance in connecting PGWUI_Server to a full-featured webserver. There is no difference between connecting PGWUI_Server to a webserver and connecting any other WSGI @@ -203,17 +218,17 @@ Configuring Routing Configuring routing means changing the URL used to access a page. Usually this is the part of the URL which comes after the domain, the -part after the *https://www.example.com* part. Alternatively, a full -URL may be supplied as a route. This can be used to direct the user -to an external website. +part after the ``https://www.example.com`` part. Alternatively, a +full URL may be supplied as a route. This can be used to direct the +user to an external website. PGWUI_Server comes with sensible defaults. Configuring routing is optional. A prefix can be put in front of every route, so that instead of the -default route of *logout* in the URL *https://www.example.com/logout* -the URL can be set to -*https://www.example.com/pgwui/programs/logout*:: +default route of ``logout`` in the URL +``https://www.example.com/logout`` the URL can be set to +``https://www.example.com/pgwui/programs/logout``:: # Set a global route prefix. URLs will look like: # https://www.example.com/pgwui/programs/logout @@ -341,6 +356,10 @@ provided by `The Dian Fossey Gorilla Fund .. _Mako: https://www.makotemplates.org/ .. _Nginx: https://www.nginx.org/ +.. _Apache: https://http.apache.org/ +.. _Hitch: https://hitch-tls.org/ +.. _HAProxy: https://www.haproxy.org .. _PostgreSQL: https://www.postgresql.org/ .. _Pyramid: https://trypyramid.com/ .. _WSGI: https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface +.. _pip: https://pip.pypa.io/en/stable/ -- 2.34.1