Skip to content

Editing PostgreSQL image content for style and consistency #270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adellape merged 2 commits into from
Apr 7, 2015
Merged

Editing PostgreSQL image content for style and consistency #270

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f551159
Editing PostgreSQL image content for style and consistency
Mar 30, 2015
1a6593c
updates as per peer review from mnagy
Mar 31, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 118 additions & 49 deletions openshift_images/postgresql.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,89 +10,158 @@
toc::[]

== Overview
The OpenShift PostgreSQL database image https://github.com/openshift/postgresql[repository] contains the sources and Dockerfiles for building PostgreSQL database images. The resulting images can be run by Docker.
The OpenShift https://github.com/openshift/postgresql[PostgreSQL] database image
repository contains the sources and Dockerfiles for building PostgreSQL database
images. The resulting images can be run by Docker.

== Versions
Currently supported versions of PostgreSQL:

* https://github.com/openshift/postgresql/tree/master/9.2[9.2]
Currently, OpenShift only supports version
https://github.com/openshift/postgresql/tree/master/9.2[9.2] of PostgreSQL.

== Base Images

The following base images are currently available:

* RHEL-7
* CentOS-7

[NOTE]
====
RHEL-7 image is not available at https://registry.hub.docker.com/[Docker Hub]. In order to perform build action on a RHEL-7 based PostgreSQL image, you need to run the build on properly subscribed RHEL-7 machine.
In order to perform a build action on a RHEL-7 based PostgreSQL image, you must
run the build on a properly subscribed RHEL-7 machine.
====

== Installation
To build PostgreSQL image, choose between the CentOS7 or RHEL7 base image:

=== RHEL-7 base image

----
$ git clone https://github.com/openshift/postgresql.git
$ cd postgresql
$ make build TARGET=rhel7 VERSION=5.5
----

=== CentOS-7 base image

----
$ git clone https://github.com/openshift/postgresql.git
$ cd postgresql
$ make build VERSION=5.5
----
To build a PostgreSQL image, use one of the following procedures, depending on
your base image:

*RHEL-7 Base Image*

To build a RHEL-7 based PostgreSQL image:

. Clone the following repository:
+
****
`$ git clone https://github.com/openshift/postgresql.git`
****
. Navigate into the directory you just created:
+
****
`$ cd postgresql`
****
. Build the image:
+
****
`$ make build TARGET=rhel7 VERSION=5.5`
****

*CentOS-7 Base Image*

To build a CentOS-7 based PostgreSQL image:

. Clone the following repository:
+
****
`$ git clone https://github.com/openshift/postgresql.git`
****
. Navigate into the directory you just created:
+
****
`$ cd postgresql`
****
. Build the image:
+
****
`$ make build VERSION=5.5`
****

[NOTE]
====
By omitting the `VERSION` parameter, the build action will be performed on all the supported versions of PostgreSQL. Since we are now supporting only version `9.2`, you can omit this parameter.
If you omit the `VERSION` parameter, then the build action is performed on all
the supported versions of PostgreSQL. Currently, only version 9.2 is supported,
so you can omit this parameter.
====

== Usage
To create a container running PostgreSQL, you need to run following commands.
To create a container running PostgreSQL, you must run the following commands.

*RHEL-7 image*

=== RHEL-7 image
****
`$ docker run -d --name _<database>_ -e POSTGRESQL_USER=_<user>_ -e POSTGRESQL_PASSWORD=_<password>_ -e POSTGRESQL_DATABASE=_<database>_ -p 5432:5432 openshift/postgresql-92-rhel7`
****

----
$ docker run -d --name postgresql_database -e POSTGRESQL_USER=user -e POSTGRESQL_PASSWORD=pass -e POSTGRESQL_DATABASE=db -p 5432:5432 openshift/postgresql-92-rhel7
----
*CentOS-7 image*

=== CentOS-7 image
****
`$ docker run -d --name _<database>_ -e POSTGRESQL_USER=_<user>_ -e POSTGRESQL_PASSWORD=_<password>_ -e POSTGRESQL_DATABASE=_<database>_ -p 5432:5432 openshift/postgresql-92-centos7`
****

----
$ 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
----
== Testing
To access and test if the application is running:

This will create a container named `postgresql_database`, with credentials `user:pass` and database `db`. To access and test if the application is running, run:
----
$ psql postgresql://user:[email protected]:5432/db <<< "SELECT 1;"
----
****
`$ psql -c "SELECT 1;" postgresql://_<user>[email protected]:5432/_<database>_`
****

== Stopping the Container
To properly stop the container:
----
$ docker stop postgresql_database
----

****
`$ docker stop _<database>_`
****

== Environment variables

* *POSTGRESQL_USER* - This variable specifies username for database user that will be created for your application to use.
The image recognizes the following environment variables that you can set
during initialization with this command:

* *POSTGRESQL_PASSWORD* - Password for the *POSTGRESQL_USER*.
****
`$ docker run -e VAR=_<variable>_`
****

* *POSTGRESQL_DATABASE* - Name of the database that will be created. *POSTGRESQL_USER* will have full rights to the database.
.Repository Organization
[cols="4a,6a",options="header"]
|===

* *POSTGRESQL_ADMIN_PASSWORD* - Password for the postgres user. This variable is optional. If not set, remote login to the postgres account will not be possible. Local connections from inside the container are always allowed without a password.
|Variable name |Description

== Volumes
|`*POSTGRESQL_USER*`
|Username for the PostgreSQL account to be created. This user has full rights to
the database.

* */var/lib/pgsql/data* - This is the database cluster directory where PostgreSQL stores database files.
|`*POSTGRESQL_PASSWORD*`
|Password for the user account.

== Settings
PostgreSQL settings can be configured by additional environment variables.
|`*POSTGRESQL_DATABASE*`
|Database name.

* *POSTGRESQL_MAX_CONNECTIONS* - The maximum number of client connections allowed.
|`*POSTGRESQL_ADMIN_PASSWORD*`
|Optional password for the `postgres` admin user. If this is not set, then
remote login to the `postgres` account is not possible. Local connections from
within the container are always permitted without a password.
|===

=== Settings

PostgreSQL settings can be configured with the following environment variables.

.Additional PostgreSQL settings
[cols="3a,6a,1a",options="header"]
|===

|Variable name |Description |Default

|`*POSTGRESQL_MAX_CONNECTIONS*`
|The maximum number of client connections allowed.
|100

|`*POSTGRESQL_SHARED_BUFFERS*`
|Configures how much memory is dedicated to PostgreSQL for caching data.
|32M
|===

== Volumes

* *POSTGRESQL_SHARED_BUFFERS* - Sets how much memory is dedicated to PostgreSQL to use for caching data.
* *_/var/lib/pgsql/data_* - This is the database cluster directory where
PostgreSQL stores database files.