diff --git a/docs/en_US/config_py.rst b/docs/en_US/config_py.rst new file mode 100644 index 000000000..37a1114d6 --- /dev/null +++ b/docs/en_US/config_py.rst @@ -0,0 +1,34 @@ +.. _config_py: + +*************************** +`The config.py File`:index: +*************************** + +There are multiple configuration files that are read at startup by pgAdmin. These +are as follows: + +* ``config.py``: This is the main configuration file, and should not be modified. + It can be used as a reference for configuration settings, that may be overridden + in one of the following files. + +* ``config_distro.py``: This file is read after ``config.py`` and is intended for + packagers to change any settings that are required for their pgAdmin distribution. + This may typically include certain paths and file locations. This file is optional, + and may be created by packagers in the same directory as ``config.py`` if + needed. + +* ``config_local.py``: This file is read after ``config_distro.py`` and is intended + for end users to change any default or packaging specific settings that they may + wish to adjust to meet local preferences or standards.This file is optional, + and may be created by users in the same directory as ``config.py`` if + needed. + +.. note:: If the SERVER_MODE setting is changed in ``config_distro.py`` or ``config_local.py``, + you will most likely need to re-set the LOG_FILE, SQLITE_PATH, SESSION_DB_PATH + and STORAGE_DIR values as well as they will have been set based on the default + configuration or overridden by the runtime. + +The default ``config.py`` file is shown below for reference: + +.. literalinclude:: ../../web/config.py + :language: python diff --git a/docs/en_US/container_deployment.rst b/docs/en_US/container_deployment.rst index 0e73673ba..c697c0adb 100644 --- a/docs/en_US/container_deployment.rst +++ b/docs/en_US/container_deployment.rst @@ -83,6 +83,21 @@ 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. +*PGADMIN_CONFIG_* + +This is a variable prefix that can be used to override any of the configuration +options in pgAdmin's *config.py* file. Add the *PGADMIN_CONFIG_* prefix to any +variable name from *config.py* and give the value in the format 'string value' +for strings, True/False for booleans or 123 for numbers. See below for an +example. + +Settings are written to */pgadmin4/config_distro.py* within the container, which +is read after */pgadmin4/config.py* and before */pgadmin4/config_local.py*. +Any settings given will therefore override anything in config.py, but can be +overridden by settings in config_local.py. + +See :ref:`config_py` for more information on the available configuration settings. + Mapped Files and Directories **************************** @@ -101,7 +116,8 @@ invocations of the container. 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. +required. Settings in config_local.py will also override anything specified in +the container environment through *PGADMIN_CONFIG_* prefixed variables. */pgadmin4/servers.json* @@ -129,8 +145,21 @@ Run a simple container over port 80: docker pull dpage/pgadmin4 docker run -p 80:80 \ - -e "PGADMIN_DEFAULT_EMAIL=user@domain.com" \ - -e "PGADMIN_DEFAULT_PASSWORD=SuperSecret" \ + -e 'PGADMIN_DEFAULT_EMAIL=user@domain.com' \ + -e 'PGADMIN_DEFAULT_PASSWORD=SuperSecret' \ + -d dpage/pgadmin4 + +Run a simple container over port 80, setting some configuration options: + +.. code-block:: bash + + docker pull dpage/pgadmin4 + docker run -p 80:80 \ + -e 'PGADMIN_DEFAULT_EMAIL=user@domain.com' \ + -e 'PGADMIN_DEFAULT_PASSWORD=SuperSecret' \ + -e 'PGADMIN_CONFIG_ENHANCED_COOKIE_PROTECTION=True' \ + -e 'PGADMIN_CONFIG_LOGIN_BANNER="Authorised users only!"' \ + -e 'PGADMIN_CONFIG_CONSOLE_LOG_LEVEL=10' \ -d dpage/pgadmin4 Run a TLS secured container using a shared config/storage directory in @@ -141,13 +170,13 @@ Run a TLS secured container using a shared config/storage directory in 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" \ + -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 diff --git a/docs/en_US/deployment.rst b/docs/en_US/deployment.rst index d375c32c1..8652c1027 100644 --- a/docs/en_US/deployment.rst +++ b/docs/en_US/deployment.rst @@ -12,7 +12,8 @@ will provide detailed information about creating a custom deployment. .. toctree:: :maxdepth: 2 - + + config_py desktop_deployment server_deployment - container_deployment \ No newline at end of file + container_deployment diff --git a/docs/en_US/desktop_deployment.rst b/docs/en_US/desktop_deployment.rst index 08a66cdc3..b5d911ff1 100644 --- a/docs/en_US/desktop_deployment.rst +++ b/docs/en_US/desktop_deployment.rst @@ -36,32 +36,10 @@ this is overridden by the desktop runtime at startup. In most environments, no Python configuration is required unless you wish to override other default settings. -There are multiple configuration files that are read at startup by pgAdmin. These -are as follows: - -* ``config.py``: This is the main configuration file, and should not be modified. - It can be used as a reference for configuration settings, that may be overridden - in one of the following files. - -* ``config_distro.py``: This file is read after ``config.py`` and is intended for - packagers to change any settings that are required for their pgAdmin distribution. - This may typically include certain paths and file locations. This file is optional, - and may be created by packagers in the same directory as ``config.py`` if - needed. - -* ``config_local.py``: This file is read after ``config_distro.py`` and is intended - for end users to change any default or packaging specific settings that they may - wish to adjust to meet local preferences or standards.This file is optional, - and may be created by users in the same directory as ``config.py`` if - needed. - -.. note:: If the SERVER_MODE setting is changed in ``config_distro.py`` or ``config_local.py``, - you will most likely need to re-set the LOG_FILE, SQLITE_PATH, SESSION_DB_PATH - and STORAGE_DIR values as well as they will have been set based on the default - configuration or overridden by the runtime. +See :ref:`config_py` for more information on configuration settings. Runtime -------- +******* When executed, the runtime will automatically try to execute the pgAdmin Python application. If execution fails, it will prompt you to adjust the Python Path diff --git a/docs/en_US/release_notes_4_13.rst b/docs/en_US/release_notes_4_13.rst index aeddce3b3..a0a3a38ef 100644 --- a/docs/en_US/release_notes_4_13.rst +++ b/docs/en_US/release_notes_4_13.rst @@ -9,6 +9,7 @@ This release contains a number of bug fixes and new features since the release o New features ************ +| `Issue #4651 `_ - Allow configuration options to be set from the environment in the container distribution. Housekeeping ************ diff --git a/docs/en_US/server_deployment.rst b/docs/en_US/server_deployment.rst index 04b788678..584403bf1 100644 --- a/docs/en_US/server_deployment.rst +++ b/docs/en_US/server_deployment.rst @@ -59,24 +59,7 @@ In order to configure pgAdmin to run in server mode, it may be necessary to configure the Python code to run in multi-user mode, and then to configure the web server to find and execute the code. -Note that there are multiple configuration files that are read at startup by -pgAdmin. These are as follows: - -* ``config.py``: This is the main configuration file, and should not be modified. - It can be used as a reference for configuration settings, that may be overridden - in one of the following files. - -* ``config_distro.py``: This file is read after ``config.py`` and is intended for - packagers to change any settings that are required for their pgAdmin distribution. - This may typically include certain paths and file locations. This file is optional, - and may be created by packagers in the same directory as ``config.py`` if - needed. - -* ``config_local.py``: This file is read after ``config_distro.py`` and is intended - for end users to change any default or packaging specific settings that they may - wish to adjust to meet local preferences or standards. This file is optional, - and may be created by administrators in the same directory as ``config.py`` if - needed. +See :ref:`config_py` for more information on configuration settings. Python ------ @@ -117,6 +100,12 @@ In order to configure the Python code, follow these steps: # chown www-data:www-data /var/lib/pgadmin4/pgadmin4.db +Hosting +******* + +There are many possible ways to host pgAdmin in server mode. Some examples are +given below: + Apache HTTPD Configuration (Windows) ------------------------------------ diff --git a/pkg/docker/Dockerfile b/pkg/docker/Dockerfile index 206cfdd33..2bf82a612 100644 --- a/pkg/docker/Dockerfile +++ b/pkg/docker/Dockerfile @@ -86,7 +86,6 @@ RUN apk add --no-cache --virtual build-deps build-base postgresql-dev libffi-dev # Copy the code COPY ./pgadmin4/web /pgadmin4 COPY ./run_pgadmin.py /pgadmin4 -COPY ./config_distro.py /pgadmin4 COPY ./entrypoint.sh /entrypoint.sh # Precompile and optimize python code to save time and space on startup diff --git a/pkg/docker/config_distro.py b/pkg/docker/config_distro.py deleted file mode 100644 index 9763f5445..000000000 --- a/pkg/docker/config_distro.py +++ /dev/null @@ -1,4 +0,0 @@ -HELP_PATH = '../../docs' -DEFAULT_BINARY_PATHS = { - 'pg': '/usr/local/pgsql-11' -} diff --git a/pkg/docker/entrypoint.sh b/pkg/docker/entrypoint.sh index f7f9b9ab3..063518576 100755 --- a/pkg/docker/entrypoint.sh +++ b/pkg/docker/entrypoint.sh @@ -1,5 +1,23 @@ #!/bin/sh +# Create config_distro.py. This has some default config, as well as anything +# provided by the user through the PGADMIN_CONFIG_* environment variables. +# Only write the file on first launch. +if [ ! -f /pgadmin4/config_distro.py ]; then + cat << EOF > /pgadmin4/config_distro.py +HELP_PATH = '../../docs' +DEFAULT_BINARY_PATHS = { + 'pg': '/usr/local/pgsql-11' +} +EOF + + # This is a bit kludgy, but necessary as the container uses BusyBox/ash as + # it's shell and not bash which would allow a much cleaner implementation + for var in $(env | grep PGADMIN_CONFIG_ | cut -d "=" -f 1); do + echo ${var#PGADMIN_CONFIG_} = $(eval "echo \$$var") >> /pgadmin4/config_distro.py + done +fi + if [ ! -f /var/lib/pgadmin/pgadmin4.db ]; then if [ -z "${PGADMIN_DEFAULT_EMAIL}" -o -z "${PGADMIN_DEFAULT_PASSWORD}" ]; then echo 'You need to specify PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD environment variables'