Add help.1 file (#162)

Atomic CLI tool shows groff formatted man page if called by atomic help <img>, so all images should support it.
Currently the man page is generated outside of the build system by pandoc -s -f markdown -t man.
Include run_doc_test in the TEST_LIST rather than standalone

9.2/Dockerfile

@@ -23,6 +23,7 @@ LABEL io.k8s.description="PostgreSQL is an advanced Object-Relational database m
 
 EXPOSE 5432
 
+ADD README.md /help.md
 ADD root /
 
 # This image must forever use UID 26 for postgres user so our volumes are

9.2/Dockerfile.rhel7

@@ -28,6 +28,7 @@ LABEL name="openshift3/postgresql-92-rhel7" \
 
 EXPOSE 5432
 
+ADD README.md /help.md
 ADD root /
 
 # This image must forever use UID 26 for postgres user so our volumes are

9.2/root/help.1

@@ -0,0 +1,12 @@
+.\"t
+.\" WARNING: Do not edit this file manually, it is generated from README.md automatically.
+.\"
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.TH "POSTGRESQL\-92\-RHEL7" "1" "February 22, 2017" "Container Image Pages" ""
+.hy
+.SH PostgreSQL Docker image
+.PP
+\f[B]The PostgreSQL 9.2 image is deprecated.\f[]
+.SH AUTHORS
+Red Hat.

9.4/root/help.1

@@ -0,0 +1,190 @@
+.\"t
+.\" WARNING: Do not edit this file manually, it is generated from README.md automatically.
+.\"
+.\"t
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.TH "POSTGRESQL\-94\-RHEL7" "1" "February 22, 2017" "Container Image Pages" ""
+.hy
+.SH PostgreSQL Docker image
+.PP
+This repository contains Dockerfiles for PostgreSQL images for general
+usage and OpenShift.
+Users can choose between RHEL and CentOS based images.
+.SS Environment variables and volumes
+.PP
+The image recognizes the following environment variables that you can
+set during initialization by passing \f[C]\-e\ VAR=VALUE\f[] to the
+Docker run command.
+.PP
+.TS
+tab(@);
+lw(26.7n) lw(43.3n).
+T{
+Variable name
+T}@T{
+Description
+T}
+_
+T{
+\f[C]POSTGRESQL_USER\f[]
+T}@T{
+User name for PostgreSQL account to be created
+T}
+T{
+\f[C]POSTGRESQL_PASSWORD\f[]
+T}@T{
+Password for the user account
+T}
+T{
+\f[C]POSTGRESQL_DATABASE\f[]
+T}@T{
+Database name
+T}
+T{
+\f[C]POSTGRESQL_ADMIN_PASSWORD\f[]
+T}@T{
+Password for the \f[C]postgres\f[] admin account (optional)
+T}
+.TE
+.PP
+The following environment variables influence the PostgreSQL
+configuration file.
+They are all optional.
+.PP
+.TS
+tab(@);
+lw(15.7n) lw(37.6n) lw(16.7n).
+T{
+Variable name
+T}@T{
+Description
+T}@T{
+Default
+T}
+_
+T{
+\f[C]POSTGRESQL_MAX_CONNECTIONS\f[]
+T}@T{
+The maximum number of client connections allowed
+T}@T{
+100
+T}
+T{
+\f[C]POSTGRESQL_MAX_PREPARED_TRANSACTIONS\f[]
+T}@T{
+Sets the maximum number of transactions that can be in the "prepared"
+state.
+If you are using prepared transactions, you will probably want this to
+be at least as large as max_connections
+T}@T{
+0
+T}
+T{
+\f[C]POSTGRESQL_SHARED_BUFFERS\f[]
+T}@T{
+Sets how much memory is dedicated to PostgreSQL to use for caching data
+T}@T{
+32M
+T}
+T{
+\f[C]POSTGRESQL_EFFECTIVE_CACHE_SIZE\f[]
+T}@T{
+Set to an estimate of how much memory is available for disk caching by
+the operating system and within the database itself
+T}@T{
+128M
+T}
+.TE
+.PP
+You can also set the following mount points by passing the
+\f[C]\-v\ /host:/container\f[] flag to Docker.
+.PP
+.TS
+tab(@);
+l l.
+T{
+Volume mount point
+T}@T{
+Description
+T}
+_
+T{
+\f[C]/var/lib/pgsql/data\f[]
+T}@T{
+PostgreSQL database cluster directory
+T}
+.TE
+.PP
+\f[B]Notice: When mouting a directory from the host into the container,
+ensure that the mounted directory has the appropriate permissions and
+that the owner and group of the directory matches the user UID or name
+which is running inside the container.\f[]
+.SS Usage
+.PP
+For this, we will assume that you are using the
+\f[C]openshift/postgresql\-92\-centos7\f[] image.
+If you want to set only the mandatory environment variables and not
+store the database in a host directory, execute the following command:
+.IP
+.nf
+\f[C]
+$\ docker\ run\ \-d\ \-\-name\ postgresql_database\ \-e\ POSTGRESQL_USER=user\ \-e\ POSTGRESQL_PASSWORD=pass\ \-e\ POSTGRESQL_DATABASE=db\ \-p\ 5432:5432\ openshift/postgresql\-92\-centos7
+\f[]
+.fi
+.PP
+This will create a container named \f[C]postgresql_database\f[] running
+PostgreSQL with database \f[C]db\f[] and user with credentials
+\f[C]user:pass\f[].
+Port 5432 will be exposed and mapped to the host.
+If you want your database to be persistent across container executions,
+also add a \f[C]\-v\ /host/db/path:/var/lib/pgsql/data\f[] argument.
+This will be the PostgreSQL database cluster directory.
+.PP
+If the database cluster directory is not initialized, the entrypoint
+script will first run
+\f[C]initdb\f[] (http://www.postgresql.org/docs/9.2/static/app-initdb.html)
+and setup necessary database users and passwords.
+After the database is initialized, or if it was already present,
+\f[C]postgres\f[] (http://www.postgresql.org/docs/9.2/static/app-postgres.html)
+is executed and will run as PID 1.
+You can stop the detached container by running
+\f[C]docker\ stop\ postgresql_database\f[].
+.SS PostgreSQL auto\-tuning
+.PP
+When the PostgreSQL image is run with the \f[C]\-\-memory\f[] parameter
+set and if there are no values provided for
+\f[C]POSTGRESQL_SHARED_BUFFERS\f[] and
+\f[C]POSTGRESQL_EFFECTIVE_CACHE_SIZE\f[] those values are automatically
+calculated based on the value provided in the \f[C]\-\-memory\f[]
+parameter.
+.PP
+The values are calculated based on the
+upstream (https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server)
+formulas.
+For the \f[C]shared_buffers\f[] we use 1/4 of given memory and for the
+\f[C]effective_cache_size\f[] we set the value to 1/2 of the given
+memory.
+.SS PostgreSQL admin account
+.PP
+The admin account \f[C]postgres\f[] has no password set by default, only
+allowing local connections.
+You can set it by setting the \f[C]POSTGRESQL_ADMIN_PASSWORD\f[]
+environment variable when initializing your container.
+This will allow you to login to the \f[C]postgres\f[] account remotely.
+Local connections will still not require a password.
+.SS Changing passwords
+.PP
+Since passwords are part of the image configuration, the only supported
+method to change passwords for the database user
+(\f[C]POSTGRESQL_USER\f[]) and \f[C]postgres\f[] admin user is by
+changing the environment variables \f[C]POSTGRESQL_PASSWORD\f[] and
+\f[C]POSTGRESQL_ADMIN_PASSWORD\f[], respectively.
+.PP
+Changing database passwords through SQL statements or any way other than
+through the environment variables aforementioned will cause a mismatch
+between the values stored in the variables and the actual passwords.
+Whenever a database container starts it will reset the passwords to the
+values stored in the environment variables.
+.SH AUTHORS
+Red Hat.