Merge pull request #802 from infosiftr/postgres-any-user

Add some notes about the caveats for "arbitrary user" support in postgres

Author: yosifkit

postgres/content.md

@@ -66,6 +66,47 @@ This optional environment variable can be used to define a different name for th
 
 This optional environment variable can be used to send arguments to `postgres initdb`. The value is a space separated string of arguments as `postgres initdb` would expect them. This is useful for adding functionality like data page checksums: `-e POSTGRES_INITDB_ARGS="--data-checksums"`.
 
+## Arbitrary `--user` Notes
+
+As of [docker-library/postgres#253](https://github.com/docker-library/postgres/pull/253), this image supports running as a (mostly) arbitrary user via `--user` on `docker run`.
+
+The main caveat to note is that `postgres` doesn't care what UID it runs as (as long as the owner of `/var/lib/postgresql/data` matches), but `initdb` *does* care (and needs the user to exist in `/etc/passwd`):
+
+```console
+$ docker run -it --rm --user www-data postgres
+The files belonging to this database system will be owned by user "www-data".
+...
+
+$ docker run -it --rm --user 1000:1000 postgres
+initdb: could not look up effective user ID 1000: user does not exist
+```
+
+The two easiest ways to get around this:
+
+1.	bind-mount `/etc/passwd` read-only from the host (if the UID you desire is a valid user on your host):
+
+	```console
+	$ docker run -it --rm --user "$(id -u):$(id -g)" -v /etc/passwd:/etc/passwd:ro postgres
+	The files belonging to this database system will be owned by user "jsmith".
+	...
+	```
+
+2.	initialize the target directory separately from the final runtime (with a `chown` in between):
+
+	```console
+	$ docker volume create pgdata
+	$ docker run -it --rm -v pgdata:/var/lib/postgresql/data postgres
+	The files belonging to this database system will be owned by user "postgres".
+	...
+	( once it's finished initializing successfully and is waiting for connections, stop it )
+	$ docker run -it --rm -v pgdata:/var/lib/postgresql/data bash chown -R 1000:1000 /var/lib/postgresql/data
+	$ docker run -it --rm --user 1000:1000 -v pgdata:/var/lib/postgresql/data postgres
+	LOG:  database system was shut down at 2017-01-20 00:03:23 UTC
+	LOG:  MultiXact member wraparound protections are now enabled
+	LOG:  autovacuum launcher started
+	LOG:  database system is ready to accept connections
+	```
+
 # How to extend this image
 
 If you would like to do additional initialization in an image derived from this one, add one or more `*.sql` or `*.sh` scripts under `/docker-entrypoint-initdb.d` (creating the directory if necessary). After the entrypoint calls `initdb` to create the default `postgres` user and database, it will run any `*.sql` files and source any `*.sh` scripts found in that directory to do further initialization before starting the service.