CamCOPS incorporates a Python web server. You can choose which one to launch:
CherryPy: a “proper” one; multithreaded; works on Windows and Linux.
Gunicorn: a “proper” one; multiprocess; Linux/UNIX only.
Pyramid: a “toy” one for debugging. (CamCOPS is written using Pyramid as its
web framework; Pyramid is excellent, but other software is generally better
for use as the web server.)
You may also want to configure a CamCOPS server behind a “front-end” web server
such as Apache. Further options to help with this are described below.
String. Default: 127.0.0.1
.
TCP/IP hostname to listen on. (See also UNIX_DOMAIN_SOCKET.)
Note some variations. For example, if your machine has an IP (v4) address of
192.168.1.1
, then under Linux you will find the following:
Using 192.168.1.1
will make the CamCOPS web server directly visible to
the network.
Using 127.0.0.1
will make it invisible to the network and visible only to
other processes on the same computer.
Using localhost
will trigger a lookup from localhost
to an IP
address, typically 127.0.0.1
.
Note
If you are using CamCOPS via Docker, see here.
Integer. Default: 8000.
TCP port number to listen on. (See also UNIX_DOMAIN_SOCKET.)
Note
If you are using CamCOPS via Docker, see here.
String. Default: none.
Filename of a UNIX domain socket (UDS) to listen on (rather than using TCP/IP).
UDS is typically faster than TCP (see e.g.
https://stackoverflow.com/questions/14973942/tcp-loopback-connection-vs-unix-domain-socket-performance).
If specified, this overrides the TCP options, HOST and PORT.
For example, /run/camcops/camcops.socket
(as per the Filesystem Hierarchy
Standard).
(Not applicable to the Pyramid test web server; CherryPy/Gunicorn only.)
Note
The socket “file” is a pseudo-file that is created by CamCOPS during
operation, and vanishes when CamCOPS stops. You don’t have to create it –
but you need to ensure that CamCOPS can write to the directory where it
lives. If you look at the file with ls -l
, you will see this:
srwxrwxrwx 1 root root 0 Jan 21 11:05 camcops.socket
^
|
The setuid bit: an indication that this is not a normal file!
String. Default: none.
SSL certificate file for HTTPS (e.g.
/etc/ssl/certs/ssl-cert-snakeoil.pem
).
(Not applicable to the Pyramid test web server; CherryPy/Gunicorn only.)
If you host CamCOPS behind Apache, it’s likely that you’ll want Apache to
handle HTTPS and CamCOPS to operate unencrypted behind a reverse proxy, in
which case don’t set this or SSL_PRIVATE_KEY.
Note
If you are using CamCOPS via Docker, see here.
String. Default: none.
SSL private key file for HTTPS (e.g.
/etc/ssl/private/ssl-cert-snakeoil.key
).
(Not applicable to the Pyramid test web server; CherryPy/Gunicorn only.)
Note
If you are using CamCOPS via Docker, see here.
Integer. Default 86400 seconds (1 day).
Time, in seconds, for which to cache static content (e.g. logos, static
scripts).
This section controls how CamCOPS creates its WSGI application. They apply to
all Python web servers provided (CherryPy, Gunicorn, Pyramid). These options
are particularly relevant if you are reverse-proxying CamCOPS behind a
front-end web server such as Apache.
Boolean. Default: false.
If a reverse proxy configuration is in use, show debugging information for it
as WSGI variable are rewritten?
A reverse proxy configuration will be used if any of the following are set (see
cardinal_pythonlib.wsgi.reverse_proxied_mw.ReverseProxiedConfig.necessary()
):
PROXY_HTTP_HOST
PROXY_REMOTE_ADDR
PROXY_REWRITE_PATH_INFO
PROXY_SCRIPT_NAME
PROXY_SERVER_NAME
PROXY_SERVER_PORT
PROXY_URL_SCHEME
TRUSTED_PROXY_HEADERS
Boolean. Default: false.
Write incoming HTTP(S) requests to the server’s log stream?
Boolean. Default: false.
[Only applicable if SHOW_REQUESTS is true.]
Write the HTTP response code to the server’s log?
Boolean. Default: false.
[Only applicable if SHOW_REQUESTS is true.]
Write the time taken by the CamCOPS WSGI app to the server’s log?
String. Default: none.
Option to set the WSGI HTTP host directly. This affects the WSGI variable
HTTP_HOST
. If not specified, the variables HTTP_X_HOST,
HTTP_X_FORWARDED_HOST
will be used, if trusted.
It is generally easiest to leave this blank and set TRUSTED_PROXY_HEADERS
instead.
String. Default: none.
Option to set the WSGI remote address directly. This affects the WSGI variable
REMOTE_ADDR
. If not specified, the variables HTTP_X_FORWARDED_FOR,
HTTP_X_REAL_IP
will be used, if trusted.
It is generally easiest to leave this blank and set TRUSTED_PROXY_HEADERS
instead.
Boolean. Default: false.
If SCRIPT_NAME
is rewritten, this option causes PATH_INFO
to be
rewritten, if it starts with SCRIPT_NAME
, to strip off SCRIPT_NAME
.
Appropriate for some front-end web browsers with limited reverse proxying
support (but do not use for Apache with ProxyPass
, because that rewrites
incoming URLs properly).
String. Default: none.
Path at which this script is mounted. Set this if you are hosting this CamCOPS
instance at a non-root path, unless you set trusted WSGI headers instead.
For example, if you are running an Apache server and want this instance of
CamCOPS to appear at /somewhere/camcops
, then (a) configure your Apache
instance to proxy requests to /somewhere/camcops/...
to this server (e.g.
via an internal TCP/IP port or UNIX socket) and (b) specify this option.
If this option is not set, then the OS environment variable SCRIPT_NAME
will be checked as well. If that is not set, the variables within
HTTP_X_SCRIPT_NAME, HTTP_X_FORWARDED_SCRIPT_NAME
will be used, if they are
trusted.
This option affects the WSGI variables SCRIPT_NAME
and PATH_INFO
.
It is generally easiest to leave this blank and set TRUSTED_PROXY_HEADERS
instead.
String. Default: none.
Option to set the WSGI server name directly. This affects the WSGI variable
SERVER_NAME
. If not specified, the variable HTTP_X_FORWARDED_SERVER
will be used, if trusted.
It is generally easiest to leave this blank and set TRUSTED_PROXY_HEADERS
instead.
Integer. Default: none.
Option to set the WSGI server port directly. This affects the WSGI variable
SERVER_PORT
. If not specified, the variable HTTP_X_FORWARDED_PORT
will
be used, if trusted.
It is generally easiest to leave this blank and set TRUSTED_PROXY_HEADERS
instead.
String. Default: none.
Option to set the WSGI scheme (e.g. http, https) directly. This affects the
WSGI variable wsgi.url_scheme
. If not specified, a variable from the
following will be used, if trusted: HTTP_X_FORWARDED_PROTO,
HTTP_X_FORWARDED_PROTOCOL, HTTP_X_FORWARDED_SCHEME, HTTP_X_SCHEME
(which can
specify a protocol) or HTTP_X_FORWARDED_HTTPS, HTTP_X_FORWARDED_SSL,
HTTP_X_HTTPS
(which can contain Boolean information about which protocol is
in use).
It is generally easiest to leave this blank and set TRUSTED_PROXY_HEADERS
instead.
When you browse to the CamCOPS web interface, CamCOPS can work out its own URL
address, even if you are hosting CamCOPS behind a proxy (see e.g.
PROXY_SCRIPT_NAME). However, CamCOPS also has a “back end”, used for scheduled
and/or slow jobs like exporting tasks. If this part of CamCOPS needs to know
its own address, it can’t work that out dynamically. You have to tell it.
Currently, this is primarily applicable to FHIR exports.
The components of the URL are specified like this:
For a CamCOPS server hosted at the root path (e.g. directly), leave
EXTERNAL_SCRIPT_NAME blank:
https://camcops.mydomain:443/path_within_camcops_application
^^^^^ ^^^^^^^^^^^^^^^^ ^^^
| | |
| | |
| | EXTERNAL_SERVER_PORT
| EXTERNAL_SERVER_NAME
EXTERNAL_URL_SCHEME
For a CamCOPS server hosted at a non-root path (e.g. via Apache as one of many
pages/applications on a single web site), specify EXTERNAL_SCRIPT_NAME:
https://camcops.mydomain:443/camcops/path_within_camcops_application
^^^^^ ^^^^^^^^^^^^^^^^ ^^^ ^^^^^^^
| | | |
| | | EXTERNAL_SCRIPT_NAME
| | EXTERNAL_SERVER_PORT
| EXTERNAL_SERVER_NAME
EXTERNAL_URL_SCHEME
Additional options for the CherryPy web server.
String. Default: localhost
.
CherryPy’s SERVER_NAME
environment entry.
Integer. Default: 10.
Number of threads for server to start with.
Integer. Default: 100.
Maximum number of threads for server to use (-1 for no limit).
BEWARE exceeding the permitted number of database connections.
Boolean. Default: true.
Log access requests etc. to the terminal (stdout/stderr)?
String. Default: /
.
Root path to serve CRATE at, WITHIN this CherryPy web server instance.
There is unlikely to be a reason to use something other than /
; do not
confuse this with the mount point within a wider, e.g. Apache, configuration,
which is set instead by the WSGI variable SCRIPT_NAME
; see the
TRUSTED_PROXY_HEADERS and PROXY_SCRIPT_NAME options.