From b2c6eae5da98dc5fc2d39e3fa81279f7e4d2096d Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Thu, 12 Dec 2019 09:04:02 -0600 Subject: [PATCH] Improve the docs accuracy and language --- README.rst | 58 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/README.rst b/README.rst index 37bcefa..28890eb 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,4 @@ -.. Copyright (C) 2018 The Meme Factory, Inc. http://www.meme.com/ +.. Copyright (C) 2018, 2019 The Meme Factory, Inc. http://www.karlpinc.com/ This file is part of PGWUI_Server. @@ -17,7 +17,7 @@ License along with this program. If not, see . - Karl O. Pinc + Karl O. Pinc .. #End Of Copyright Marker# @@ -27,21 +27,28 @@ PGWUI_Server Short Documentation ------------------- -PGWUI_Server contains what's needed to put the PGWUI components on the +PGWUI_Server contains what's needed to put PGWUI components on the web. It should be installed by most PGWUI users. The alternative to installing PGWUI_Server is writing your own `Pyramid`_ application. PGWUI_Server stands for `PostgreSQL`_ Web User Interface, Server support. -PGWUI_Server contains a basic webserver for those who want something -simple and stand-alone. More advanced users may use PGWUI_Server's -WSGI interface to connect to a more full-featured webserver such as -Apache or Nginx. +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. -PGWUI_Server does not support HTTPS out-of-the-box. It is designed to -stand behind a reverse web proxy or an advanced WSGI web server which -is expected to supply this functionality. Nginx, Apache, and many -other full-featured web servers are all suitable. +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. + +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. PGWUI_Server supports configuration using a traditional *.ini* file. @@ -77,20 +84,32 @@ Install into a Python 3 virtual environment with commands like:: Startup and Usage ----------------- -Start the stand-alone webserver with:: +PGWUI_Server comes with an example configuration which connects it to +the *waitress* `WSGI`_ webserver and configures waitress. The +simplest approach is to install and use waitress as the application's +WSGI server. + +Waitress is not a requirement and is not automatically installed. To +use another WSGI capable webserver modify the appropriate sections of +the supplied configuration file using the comments written into the +file as a guide. - pgwui_venv/bin/pserve pgwui.ini +Use *pserve* to start PGWUI and the stand-alone WSGI webserver you +installed:: -PGWUI_Server comes with *waitress* configured as the webserver started -by pserve, and a default waitress configuration. The simplest approach -is to install and use waitress as the applications WSGI server. + pgwui_venv/bin/pserve /etc/pgwui.ini The installation can then be accessed via URLs similar to:: http://localhost:6543/logout +Automating startup at boot time is OS dependent. + +Troubleshooting +^^^^^^^^^^^^^^^ + Minimal error reporting is done on stderr to help diagnose startup -failure. Full error reporting is done via logging so when there are +failure. Full error reporting is done via logging. When there are problems it is important to check the log and the logging configuration. @@ -145,12 +164,12 @@ Replace the ``location / { ... }`` section appearing in the default `Nginx`_ documentation. It is beyond the scope of this document to describe how to use -PGWUI_Server's WSGI support, or the nuances of reverse-proxy +PGWUI_Server's WSGI support or the the nuances of reverse-proxy configuration. Any WSGI web server can be used with PGWUI_Server, as can any reverse web-proxy. Again, ``pserve`` with ``waitress`` does not support HTTPS. Consult your -webserver's documentation for HTTPS support. +webserver's HTTPS documentation. Configuration @@ -324,3 +343,4 @@ provided by `The Dian Fossey Gorilla Fund .. _Nginx: https://www.nginx.org/ .. _PostgreSQL: https://www.postgresql.org/ .. _Pyramid: https://trypyramid.com/ +.. _WSGI: https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface -- 2.34.1