From 59a9d9d1012f6e0a63f6a9011e07332bef89d41d Mon Sep 17 00:00:00 2001 From: Maxim Marinchenko Date: Fri, 10 Jun 2022 17:14:21 +0500 Subject: [PATCH 1/7] Remove deprecated version element from stack.yml --- postgres/stack.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/postgres/stack.yml b/postgres/stack.yml index 3994b0c470c2..f650d1e579dc 100644 --- a/postgres/stack.yml +++ b/postgres/stack.yml @@ -1,5 +1,4 @@ # Use postgres/example user/password credentials -version: '3.1' services: From 9e1282368c18f1918039577bff3dd3b073a1cd0b Mon Sep 17 00:00:00 2001 From: Maxim Marinchenko Date: Fri, 10 Jun 2022 18:04:37 +0500 Subject: [PATCH 2/7] Update links in content.md --- postgres/content.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/postgres/content.md b/postgres/content.md index be45394a8f61..107cbfe16b50 100644 --- a/postgres/content.md +++ b/postgres/content.md @@ -20,13 +20,13 @@ The default `postgres` user and database are created in the entrypoint with `ini > The postgres database is a default database meant for use by users, utilities and third party applications. > -> [postgresql.org/docs](http://www.postgresql.org/docs/9.5/interactive/app-initdb.html) +> [postgresql.org/docs](https://www.postgresql.org/docs/current/app-initdb.html) ## ... or via `psql` ```console $ docker run -it --rm --network some-network %%IMAGE%% psql -h some-postgres -U postgres -psql (9.5.0) +psql (14.4) Type "help" for help. postgres=# SELECT 1; @@ -109,7 +109,7 @@ $ docker run -d \ %%IMAGE%% ``` -This is an environment variable that is not Docker specific. Because the variable is used by the `postgres` server binary (see the [PostgreSQL docs](https://www.postgresql.org/docs/11/app-postgres.html#id-1.9.5.14.7)), the entrypoint script takes it into account. +This is an environment variable that is not Docker specific. Because the variable is used by the `postgres` server binary (see the [PostgreSQL docs](https://www.postgresql.org/docs/current/app-postgres.html#id-1.9.5.14.7)), the entrypoint script takes it into account. ## Docker Secrets @@ -146,7 +146,7 @@ Additionally, as of [docker-library/postgres#253](https://github.com/docker-libr ## Database Configuration -There are many ways to set PostgreSQL server configuration. For information on what is available to configure, see the postgresql.org [docs](https://www.postgresql.org/docs/current/static/runtime-config.html) for the specific version of PostgreSQL that you are running. Here are a few options for setting configuration: +There are many ways to set PostgreSQL server configuration. For information on what is available to configure, see the [PostgreSQL docs](https://www.postgresql.org/docs/current/runtime-config.html) for the specific version of PostgreSQL that you are running. Here are a few options for setting configuration: - Use a custom config file. Create a config file and get it into the container. If you need a starting place for your config file you can use the sample provided by PostgreSQL which is available in the container at `/usr/share/postgresql/postgresql.conf.sample` (`/usr/local/share/postgresql/postgresql.conf.sample` in Alpine variants). @@ -162,7 +162,7 @@ There are many ways to set PostgreSQL server configuration. For information on w $ docker run -d --name some-postgres -v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% -c 'config_file=/etc/postgresql/postgresql.conf' ``` -- Set options directly on the run line. The entrypoint script is made so that any options passed to the docker command will be passed along to the `postgres` server daemon. From the [docs](https://www.postgresql.org/docs/current/static/app-postgres.html) we see that any option available in a `.conf` file can be set via `-c`. +- Set options directly on the run line. The entrypoint script is made so that any options passed to the docker command will be passed along to the `postgres` server daemon. From the [PostgreSQL docs](https://www.postgresql.org/docs/current/app-postgres.html#id-1.9.5.14.6.3) we see that any option available in a `.conf` file can be set via `-c`. ```console $ docker run -d --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% -c shared_buffers=256MB -c max_connections=200 @@ -184,9 +184,9 @@ Also of note, Alpine-based variants do *not* support locales; see ["Character se ## Additional Extensions -When using the default (Debian-based) variants, installing additional extensions (such as PostGIS) should be as simple as installing the relevant packages (see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/4eb614133d6aa87bfc5c952d24b7eb1f499e5c7c/12-3.0/Dockerfile) for a concrete example). +When using the default (Debian-based) variants, installing additional extensions (such as PostGIS) should be as simple as installing the relevant packages (see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/master/14-3.2/Dockerfile) for a concrete example). -When using the Alpine variants, any postgres extension not listed in [postgres-contrib](https://www.postgresql.org/docs/10/static/contrib.html) will need to be compiled in your own image (again, see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/4eb614133d6aa87bfc5c952d24b7eb1f499e5c7c/12-3.0/alpine/Dockerfile) for a concrete example). +When using the Alpine variants, any postgres extension not listed in [postgres-contrib](https://www.postgresql.org/docs/current/contrib.html) will need to be compiled in your own image (again, see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/master/14-3.2/alpine/Dockerfile) for a concrete example). # Arbitrary `--user` Notes @@ -235,7 +235,7 @@ The three easiest ways to get around this: If there is no database when `postgres` starts in a container, then `postgres` will create the default database for you. While this is the expected behavior of `postgres`, this means that it will not accept incoming connections during that time. This may cause issues when using automation tools, such as `docker-compose`, that start several containers simultaneously. -Also note that the default `/dev/shm` size for containers is 64MB. If the shared memory is exhausted you will encounter `ERROR: could not resize shared memory segment . . . : No space left on device`. You will want to pass [`--shm-size=256MB`](https://docs.docker.com/engine/reference/run/#runtime-constraints-on-resources) for example to `docker run`, or alternatively in [`docker-compose`](https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir) +Also note that the default `/dev/shm` size for containers is 64MB. If the shared memory is exhausted you will encounter `ERROR: could not resize shared memory segment . . . : No space left on device`. You will want to pass [`--shm-size=256MB`](https://docs.docker.com/engine/reference/run/#runtime-constraints-on-resources) for example to `docker run`, or alternatively in [`docker-compose`](https://docs.docker.com/compose/compose-file/#shm_size). See ["IPVS connection timeout issue" in the Docker Success Center](https://success.docker.com/article/ipvs-connection-timeout-issue) for details about IPVS connection timeouts which will affect long-running idle connections to PostgreSQL in Swarm Mode using overlay networks. @@ -243,8 +243,8 @@ See ["IPVS connection timeout issue" in the Docker Success Center](https://succe **Important note:** There are several ways to store data used by applications that run in Docker containers. We encourage users of the `%%IMAGE%%` images to familiarize themselves with the options available, including: -- Let Docker manage the storage of your database data [by writing the database files to disk on the host system using its own internal volume management](https://docs.docker.com/engine/tutorials/dockervolumes/#adding-a-data-volume). This is the default and is easy and fairly transparent to the user. The downside is that the files may be hard to locate for tools and applications that run directly on the host system, i.e. outside containers. -- Create a data directory on the host system (outside the container) and [mount this to a directory visible from inside the container](https://docs.docker.com/engine/tutorials/dockervolumes/#mount-a-host-directory-as-a-data-volume). This places the database files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files. The downside is that the user needs to make sure that the directory exists, and that e.g. directory permissions and other security mechanisms on the host system are set up correctly. +- Let Docker manage the storage of your database data [by writing the database files to disk on the host system using its own internal volume management](https://docs.docker.com/storage/volumes/). This is the default and is easy and fairly transparent to the user. The downside is that the files may be hard to locate for tools and applications that run directly on the host system, i.e. outside containers. +- Create a data directory on the host system (outside the container) and [mount this to a directory visible from inside the container](https://docs.docker.com/storage/bind-mounts/). This places the database files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files. The downside is that the user needs to make sure that the directory exists, and that e.g. directory permissions and other security mechanisms on the host system are set up correctly. The Docker documentation is a good starting point for understanding the different storage options and variations, and there are multiple blogs and forum postings that discuss and give advice in this area. We will simply show the basic procedure here for the latter option above: From 5489842cba6abada98f14b657a4113135d553fcf Mon Sep 17 00:00:00 2001 From: Maxim Marinchenko Date: Fri, 10 Jun 2022 18:18:34 +0500 Subject: [PATCH 3/7] Update version in dockerfile snippet --- postgres/content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/postgres/content.md b/postgres/content.md index 107cbfe16b50..f5634611e065 100644 --- a/postgres/content.md +++ b/postgres/content.md @@ -173,7 +173,7 @@ There are many ways to set PostgreSQL server configuration. For information on w You can extend the Debian-based images with a simple `Dockerfile` to set a different locale. The following example will set the default locale to `de_DE.utf8`: ```dockerfile -FROM %%IMAGE%%:9.4 +FROM %%IMAGE%%:14.4 RUN localedef -i de_DE -c -f UTF-8 -A /usr/share/locale/locale.alias de_DE.UTF-8 ENV LANG de_DE.utf8 ``` From 1cae1080c8e2e22dd27945685804990e8b8b99c7 Mon Sep 17 00:00:00 2001 From: Maxim Marinchenko Date: Sat, 11 Jun 2022 00:10:30 +0500 Subject: [PATCH 4/7] Revert commit 59a9d9d --- postgres/stack.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/postgres/stack.yml b/postgres/stack.yml index f650d1e579dc..3994b0c470c2 100644 --- a/postgres/stack.yml +++ b/postgres/stack.yml @@ -1,4 +1,5 @@ # Use postgres/example user/password credentials +version: '3.1' services: From bfae2b38d8f2d94089c24f1f677f45382643b325 Mon Sep 17 00:00:00 2001 From: Maxim Marinchenko Date: Sat, 11 Jun 2022 00:13:14 +0500 Subject: [PATCH 5/7] Update postgres version in content.md to 14.3 --- postgres/content.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/postgres/content.md b/postgres/content.md index f5634611e065..b74284883deb 100644 --- a/postgres/content.md +++ b/postgres/content.md @@ -26,7 +26,7 @@ The default `postgres` user and database are created in the entrypoint with `ini ```console $ docker run -it --rm --network some-network %%IMAGE%% psql -h some-postgres -U postgres -psql (14.4) +psql (14.3) Type "help" for help. postgres=# SELECT 1; @@ -173,7 +173,7 @@ There are many ways to set PostgreSQL server configuration. For information on w You can extend the Debian-based images with a simple `Dockerfile` to set a different locale. The following example will set the default locale to `de_DE.utf8`: ```dockerfile -FROM %%IMAGE%%:14.4 +FROM %%IMAGE%%:14.3 RUN localedef -i de_DE -c -f UTF-8 -A /usr/share/locale/locale.alias de_DE.UTF-8 ENV LANG de_DE.utf8 ``` From 7e861ac83ecb17c0579e74f3facc98a00f182d2a Mon Sep 17 00:00:00 2001 From: Maxim Marinchenko Date: Sat, 11 Jun 2022 00:26:51 +0500 Subject: [PATCH 6/7] Use specific commit/version links in content.md --- postgres/content.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/postgres/content.md b/postgres/content.md index b74284883deb..4463b24cc848 100644 --- a/postgres/content.md +++ b/postgres/content.md @@ -20,7 +20,7 @@ The default `postgres` user and database are created in the entrypoint with `ini > The postgres database is a default database meant for use by users, utilities and third party applications. > -> [postgresql.org/docs](https://www.postgresql.org/docs/current/app-initdb.html) +> [postgresql.org/docs](https://www.postgresql.org/docs/14/app-initdb.html) ## ... or via `psql` @@ -56,7 +56,7 @@ This environment variable is required for you to use the PostgreSQL image. It mu **Note 1:** The PostgreSQL image sets up `trust` authentication locally so you may notice a password is not required when connecting from `localhost` (inside the same container). However, a password will be required if connecting from a different host/container. -**Note 2:** This variable defines the superuser password in the PostgreSQL instance, as set by the `initdb` script during initial container startup. It has no effect on the `PGPASSWORD` environment variable that may be used by the `psql` client at runtime, as described at [https://www.postgresql.org/docs/current/libpq-envars.html](https://www.postgresql.org/docs/current/libpq-envars.html). `PGPASSWORD`, if used, will be specified as a separate environment variable. +**Note 2:** This variable defines the superuser password in the PostgreSQL instance, as set by the `initdb` script during initial container startup. It has no effect on the `PGPASSWORD` environment variable that may be used by the `psql` client at runtime, as described at [https://www.postgresql.org/docs/14/libpq-envars.html](https://www.postgresql.org/docs/14/libpq-envars.html). `PGPASSWORD`, if used, will be specified as a separate environment variable. ### `POSTGRES_USER` @@ -80,15 +80,15 @@ This optional environment variable can be used to define another location for th ### `POSTGRES_HOST_AUTH_METHOD` -This optional variable can be used to control the `auth-method` for `host` connections for `all` databases, `all` users, and `all` addresses. If unspecified then [`scram-sha-256` password authentication](https://www.postgresql.org/docs/current/auth-password.html) is used (in 14+; `md5` in older releases). On an uninitialized database, this will populate `pg_hba.conf` via this approximate line: +This optional variable can be used to control the `auth-method` for `host` connections for `all` databases, `all` users, and `all` addresses. If unspecified then [`scram-sha-256` password authentication](https://www.postgresql.org/docs/14/auth-password.html) is used (in 14+; `md5` in older releases). On an uninitialized database, this will populate `pg_hba.conf` via this approximate line: ```console echo "host all all all $POSTGRES_HOST_AUTH_METHOD" >> pg_hba.conf ``` -See the PostgreSQL documentation on [`pg_hba.conf`](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html) for more information about possible values and their meanings. +See the PostgreSQL documentation on [`pg_hba.conf`](https://www.postgresql.org/docs/14/auth-pg-hba-conf.html) for more information about possible values and their meanings. -**Note 1:** It is not recommended to use [`trust`](https://www.postgresql.org/docs/current/auth-trust.html) since it allows anyone to connect without a password, even if one is set (like via `POSTGRES_PASSWORD`). For more information see the PostgreSQL documentation on [*Trust Authentication*](https://www.postgresql.org/docs/current/auth-trust.html). +**Note 1:** It is not recommended to use `trust` since it allows anyone to connect without a password, even if one is set (like via `POSTGRES_PASSWORD`). For more information see the PostgreSQL documentation on [*Trust Authentication*](https://www.postgresql.org/docs/14/auth-trust.html). **Note 2:** If you set `POSTGRES_HOST_AUTH_METHOD` to `trust`, then `POSTGRES_PASSWORD` is not required. @@ -109,7 +109,7 @@ $ docker run -d \ %%IMAGE%% ``` -This is an environment variable that is not Docker specific. Because the variable is used by the `postgres` server binary (see the [PostgreSQL docs](https://www.postgresql.org/docs/current/app-postgres.html#id-1.9.5.14.7)), the entrypoint script takes it into account. +This is an environment variable that is not Docker specific. Because the variable is used by the `postgres` server binary (see the [PostgreSQL docs](https://www.postgresql.org/docs/14/app-postgres.html#id-1.9.5.14.7)), the entrypoint script takes it into account. ## Docker Secrets @@ -146,7 +146,7 @@ Additionally, as of [docker-library/postgres#253](https://github.com/docker-libr ## Database Configuration -There are many ways to set PostgreSQL server configuration. For information on what is available to configure, see the [PostgreSQL docs](https://www.postgresql.org/docs/current/runtime-config.html) for the specific version of PostgreSQL that you are running. Here are a few options for setting configuration: +There are many ways to set PostgreSQL server configuration. For information on what is available to configure, see the [PostgreSQL docs](https://www.postgresql.org/docs/14/runtime-config.html) for the specific version of PostgreSQL that you are running. Here are a few options for setting configuration: - Use a custom config file. Create a config file and get it into the container. If you need a starting place for your config file you can use the sample provided by PostgreSQL which is available in the container at `/usr/share/postgresql/postgresql.conf.sample` (`/usr/local/share/postgresql/postgresql.conf.sample` in Alpine variants). @@ -162,7 +162,7 @@ There are many ways to set PostgreSQL server configuration. For information on w $ docker run -d --name some-postgres -v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% -c 'config_file=/etc/postgresql/postgresql.conf' ``` -- Set options directly on the run line. The entrypoint script is made so that any options passed to the docker command will be passed along to the `postgres` server daemon. From the [PostgreSQL docs](https://www.postgresql.org/docs/current/app-postgres.html#id-1.9.5.14.6.3) we see that any option available in a `.conf` file can be set via `-c`. +- Set options directly on the run line. The entrypoint script is made so that any options passed to the docker command will be passed along to the `postgres` server daemon. From the [PostgreSQL docs](https://www.postgresql.org/docs/14/app-postgres.html#id-1.9.5.14.6.3) we see that any option available in a `.conf` file can be set via `-c`. ```console $ docker run -d --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% -c shared_buffers=256MB -c max_connections=200 @@ -184,9 +184,9 @@ Also of note, Alpine-based variants do *not* support locales; see ["Character se ## Additional Extensions -When using the default (Debian-based) variants, installing additional extensions (such as PostGIS) should be as simple as installing the relevant packages (see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/master/14-3.2/Dockerfile) for a concrete example). +When using the default (Debian-based) variants, installing additional extensions (such as PostGIS) should be as simple as installing the relevant packages (see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/81a0b55/14-3.2/Dockerfile) for a concrete example). -When using the Alpine variants, any postgres extension not listed in [postgres-contrib](https://www.postgresql.org/docs/current/contrib.html) will need to be compiled in your own image (again, see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/master/14-3.2/alpine/Dockerfile) for a concrete example). +When using the Alpine variants, any postgres extension not listed in [postgres-contrib](https://www.postgresql.org/docs/14/contrib.html) will need to be compiled in your own image (again, see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/81a0b55/14-3.2/alpine/Dockerfile) for a concrete example). # Arbitrary `--user` Notes From ad59066b8b83cb5773ca165304243f8f3a358ef2 Mon Sep 17 00:00:00 2001 From: Maxim Marinchenko Date: Sat, 11 Jun 2022 08:20:58 +0500 Subject: [PATCH 7/7] Remove "IPVS connection timeout issue" link --- postgres/content.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/postgres/content.md b/postgres/content.md index 4463b24cc848..1ac914e850cb 100644 --- a/postgres/content.md +++ b/postgres/content.md @@ -237,8 +237,6 @@ If there is no database when `postgres` starts in a container, then `postgres` w Also note that the default `/dev/shm` size for containers is 64MB. If the shared memory is exhausted you will encounter `ERROR: could not resize shared memory segment . . . : No space left on device`. You will want to pass [`--shm-size=256MB`](https://docs.docker.com/engine/reference/run/#runtime-constraints-on-resources) for example to `docker run`, or alternatively in [`docker-compose`](https://docs.docker.com/compose/compose-file/#shm_size). -See ["IPVS connection timeout issue" in the Docker Success Center](https://success.docker.com/article/ipvs-connection-timeout-issue) for details about IPVS connection timeouts which will affect long-running idle connections to PostgreSQL in Swarm Mode using overlay networks. - ## Where to Store Data **Important note:** There are several ways to store data used by applications that run in Docker containers. We encourage users of the `%%IMAGE%%` images to familiarize themselves with the options available, including: