volumes-and-data-persistence.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.
-->

# COmanage Match Volumes and Data Persistence

COmanage Match requires a relational database. See other documentation in 
this repository for examples of how to orchestrate a COmanage Match container
together with an container providing a relational database service, and for details on how
to configure the COmanage Match container to connect to the database.

Additionally COmanage Match *requires* a persistent directory into which
a few files and a specific directory structure needed by COmanage Match
will be written. 

*The persistent directory must be provided either using a Docker volume
or a bind mount.*

The directory path inside the container that must be mounted
is `/src/comanage-match/local`.

For example to use a bind mount from the local Docker engine host:

```
sudo mkdir -p /opt/comanage-match-local
```

and then when instantiating the container

```
docker run -d \
  --name comanage-match \
  -v /opt/comanage-match-local:/srv/comanage-match/local \
  -p 80:80 \
  -p 443:443 \
  comanage-match:1.0.0-shibboleth-sp-1
```

After the image is instantiated into a container for the first time
the entrypoint script will create the necessary directory structure
along with the `database.php` and other necessary files using
database and other details found in 
[environment variables](./comanage-match-common-environment-variables.md).

*After the first instantiation of the container later restarts will not overwrite
database configuration or any other details in the persistent directory, even if the
values for the environment variables change*.