mirror of
https://github.com/pgadmin-org/pgadmin4.git
synced 2024-11-22 08:46:39 -06:00
245 lines
7.3 KiB
ReStructuredText
245 lines
7.3 KiB
ReStructuredText
.. _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;
|
|
}
|
|
}
|