.. _container_deployment:

*****************************
`Container Deployment`:index:
*****************************

pgAdmin can be deployed in a container using the image at:

    https://hub.docker.com/r/dpage/pgadmin4/

PostgreSQL Utilities
********************

The PostgreSQL utilities *pg_dump*, *pg_dumpall*, *pg_restore* and *psql* are
included in the container to allow backups to be created and restored and other
maintenance functions to be executed. Multiple versions are included in the
following directories to allow use with different versions of the database
server:

* PostgreSQL 9.4: */usr/local/pgsql-9.4*
* PostgreSQL 9.5: */usr/local/pgsql-9.5*
* PostgreSQL 9.6: */usr/local/pgsql-9.6*
* PostgreSQL 10: */usr/local/pgsql-10*
* PostgreSQL 11: */usr/local/pgsql-11*

The most recent version of the utilities is used by default; this may be
changed in the :ref:`preferences`.

Environment Variables
*********************

The container will accept the following variables at startup:

*PGADMIN_DEFAULT_EMAIL*

This is the email address used when setting up the initial administrator account
to login to pgAdmin. This variable is required and must be set at launch time.

*PGADMIN_DEFAULT_PASSWORD*

This is the password used when setting up the initial administrator account to
login to pgAdmin. This variable is required and must be set at launch time.

*PGADMIN_ENABLE_TLS*

Default: <null>

If left un-set, the container will listen on port 80 for connections in plain
text. If set to any value, the container will listen on port 443 for TLS
connections.

When TLS is enabled, a certificate and key must be provided. Typically these
should be stored on the host file system and mounted from the container. The
expected paths are /certs/server.crt and /certs/server.key

*PGADMIN_LISTEN_ADDRESS*

Default: [::]

Specify the local address that the servers listens on. The default should work
for most users - in IPv4-only environments, this may need to be set to
127.0.0.1.

*PGADMIN_LISTEN_PORT*

Default: 80 or 443 (if TLS is enabled)

Allows the port that the server listens on to be set to a specific value rather
than using the default.

*PGADMIN_SERVER_JSON_FILE*

Default: /pgadmin4/servers.json

Override the default file path for the server definition list. See the
/pgadmin4/servers.json mapped file below for more information.

*GUNICORN_THREADS*

Default: 25

Adjust the number of threads the Gunicorn server uses to handle incoming
requests. This should typically be left as-is, except in highly loaded systems
where it may be increased.

Mapped Files and Directories
****************************

The following files or directories can be mapped from the container onto the
host machine to allow configuration to be customised and shared between
instances:

*/var/lib/pgadmin*

This is the working directory in which pgAdmin stores session data, user files,
configuration files, and it's configuration database. Mapping this directory
onto the host machine gives you an easy way to maintain configuration between
invocations of the container.

*/pgadmin4/config_local.py*

This file can be used to override configuration settings in pgAdmin. Settings
found in config.py can be overridden with deployment specific values if
required.

*/pgadmin4/servers.json*

If this file is mapped, server definitions found in it will be loaded at launch
time. This allows connection information to be pre-loaded into the instance of
pgAdmin in the container. Note that server definitions are only loaded on first
launch, i.e. when the configuration database is created, and not on subsequent
launches using the same configuration database.

*/certs/server.cert*

If TLS is enabled, this file will be used as the servers TLS certificate.

*/certs/server.key*

If TLS is enabled, this file will be used as the key file for the servers TLS
certificate.

Examples
********

Run a simple container over port 80:

.. code-block:: bash

    docker pull dpage/pgadmin4
    docker run -p 80:80 \
        -e "PGADMIN_DEFAULT_EMAIL=user@domain.com" \
        -e "PGADMIN_DEFAULT_PASSWORD=SuperSecret" \
        -d dpage/pgadmin4

Run a TLS secured container using a shared config/storage directory in
/private/var/lib/pgadmin on the host, and servers pre-loaded from
/tmp/servers.json on the host:

.. code-block:: bash

    docker pull dpage/pgadmin4
    docker run -p 443:443 \
        -v "/private/var/lib/pgadmin:/var/lib/pgadmin" \
        -v "/path/to/certificate.cert:/certs/server.cert" \
        -v "/path/to/certificate.key:/certs/server.key" \
        -v "/tmp/servers.json:/servers.json" \
        -e "PGADMIN_DEFAULT_EMAIL=user@domain.com" \
        -e "PGADMIN_DEFAULT_PASSWORD=SuperSecret" \
        -e "PGADMIN_ENABLE_TLS=True" \
        -d dpage/pgadmin4

Reverse Proxying
****************

Sometimes it's desirable to have users connect to pgAdmin through a reverse
proxy rather than directly to the container it's running in. The following
examples show how this can be achieved. In all cases, pgAdmin is running in a
container on the same host, with port 5050 on the host mapped to port 80 on the
container, for example:

.. code-block:: bash

    docker pull dpage/pgadmin4
    docker run -p 5050:80 \
        -e "PGADMIN_DEFAULT_EMAIL=user@domain.com" \
        -e "PGADMIN_DEFAULT_PASSWORD=SuperSecret" \
        -d dpage/pgadmin4

HTTP via Nginx
--------------

A configuration similar to the following can be used to create a simple HTTP
reverse proxy listening for all hostnames with Nginx:

.. code-block:: nginx

    server {
        listen 80;
        server_name _;

        location / {
            proxy_set_header Host $host;
            proxy_pass http://localhost:5050/;
            proxy_redirect off;
        }
    }

If you wish to host pgAdmin under a subdirectory rather than on the root of the
server, you must specify the location and set the *X-Script-Name* header which
tells the pgAdmin container how to rewrite paths:

.. code-block:: nginx

    server {
        listen 80;
        server_name _;

        location /pgadmin4/ {
            proxy_set_header X-Script-Name /pgadmin4;
            proxy_set_header Host $host;
            proxy_pass http://localhost:5050/;
            proxy_redirect off;
        }
    }

HTTPS via Nginx
---------------

The following configuration can be used to serve pgAdmin over HTTPS to the user
whilst the backend container is serving plain HTTP to the proxy server. In this
configuration we not only set *X-Script-Name*, but also *X-Scheme* to tell the
pgAdmin server to generate any URLs using the correct scheme. A redirect from
HTTP to HTTPS is also included. The certificate and key paths may need to be
adjusted as appropriate to the specific deployment:

.. code-block:: nginx

    server {
        listen 80;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443;
        server_name _;

        ssl_certificate /etc/nginx/server.crt;
        ssl_certificate_key /etc/nginx/server.key;

        ssl on;
        ssl_session_cache builtin:1000 shared:SSL:10m;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
        ssl_prefer_server_ciphers on;

        location /pgadmin4/ {
            proxy_set_header X-Script-Name /pgadmin4;
            proxy_set_header X-Scheme $scheme;
            proxy_set_header Host $host;
            proxy_pass http://localhost:5050/;
            proxy_redirect off;
        }
    }