README.md

<!--
COmanage Docker documentation

Portions licensed to the University Corporation for Advanced Internet
Development, Inc. ("UCAID") under one or more contributor license agreements.
See the NOTICE file distributed with this work for additional information
regarding copyright ownership.

UCAID licenses this file to you under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
# PostgreSQL for COmanage Match

Intended to build a PostgreSQL image for use with COmanage Match.

## Build Arguments

No arguments are required for building the image.

The following arguments may be supplied during the build:

```
--build-arg COMANAGE_MATCH_POSTGRES_DATABASE=<name of database to use with COmanage Match>
--build-arg COMANAGE_MATCH_POSTGRES_USER=<database username>
--build-arg COMANAGE_MATCH_POSTGRES_USER_PASSWORD=<database password>
```

## Building

```
docker build \
  -t comanage-match-postgres:<tag> .
```

## Building Example

```
export COMANAGE_MATCH_POSTGRES_IMAGE_VERSION=1
TAG="${COMANAGE_MATCH_POSTGRES_IMAGE_VERSION}"
docker build \
  -t comanage-match-postgres:$TAG .
```

## Volumes and Data Persistence

You must provide a volume or bind mount that mounts to `/var/lib/postgresql/data`
inside the container to persist data saved to the relational database.

## Environment Variables

The image supports the environment variables below and the `_FILE`
[convention](../docs/comanage-match-common-environment-variables.md):

`POSTGRES_USER`

* Description: superuser
* Required: yes
* Default: `postgres`
* Example: `db_user`
* Note: Most deployers use the default.

`POSTGRES_PASSWORD`

* Description: password for superuser
* Required: no
* Default: none
* Example: `l7cX28O3mt03y41EndjM`
* Note: If you do not set a password for the superuser then
any client with access to the container may connect to the database.

`COMANAGE_MATCH_POSTGRES_DATABASE`

* Description: COmanage Registry database
* Required: yes
* Default: `registry`
* Example: `comanage_registry`

`COMANAGE_MATCH_POSTGRES_USER`

* Description: COmanage Registry database user
* Required: yes
* Default: `registry_user`
* Example: `comanage_registry_user`

`COMANAGE_MATCH_POSTGRES_USER_PASSWORD`

* Description: password for database user
* Required: no
* Default: none
* Example: `5Aw9SzS4xqYi7daHw57c`
* Note: If you do not set a password for the COmanage Registry user then
any client with access to the container may connect to the database.

## Authentication

If you do not set a password for the superuser or the COmanage Match user then
any client with access to the container may connect to the database.

## Ports

The image listens for traffic on port 5432.

## Running

See other documentation in this repository for details on how to orchestrate
running this image with other images using an orchestration tool like
Docker Compose, Docker Swarm, or Kubernetes.

To run this image:

```
docker run -d \
  --name comanage-match-database \
  -v /tmp/postgres-data:/var/lib/postgresql/data \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=superuser_password \
  -e COMANAGE_MATCH_POSTGRES_DATABASE=registry \
  -e COMANAGE_MATCH_POSTGRES_USER=match_user \
  -e COMANAGE_MATCH_POSTGRES_USER_PASSWORD=password \
  comanage-match-postgres
```

## Logging

PostgreSQL logs to the stdout and stderr of the container.

## Connecting

After breaking into the container you may connect to the
COmanage Match database as the COmanage Match database
user by running

```
psql -h 127.0.0.1 ${COMANAGE_MATCH_POSTGRES_DATABASE} ${COMANAGE_MATCH_POSTGRES_USER}
```

For example

```
# psql -h 127.0.0.1 match match_user
Password for user match_user: 
psql (11.0.0)
Type "help" for help.

match=>
```

## Backups

A common strategy for backing up the database is to run another temporary
container that executes the `pg_dump` command. You need to be sure that the
temporary container and the database container use the same network.

An example is

```
docker run \
    -it \
    --rm \
    --network temp_default \
    comanage-match-postgres \
    pg_dump \
        -h comanage-match-database \
        -U match_user \
        match
```

The output from the `pg_dump` command is sent to the stdout of the temporary
container and may be redirected to a file.