evaluation.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.
-->

# Evaluating COmanage Match using Docker

Follow these steps to build and run a simple deployment of COmanage Match
suitable for evaluation purposes.

* Install Docker. These instructions require version 17.05 or higher.

* Install [Docker Compose](https://docs.docker.com/compose/). These instructions require 
version 1.13.0 or higher.

* Clone this repository:

```
git clone https://github.internet2.edu/COmanage/docker.git
cd docker/comanage-match
```

* Define the shell variable `COMANAGE_MATCH_VERSION` to be the version
of COmanage Match you want to deploy. See the
[COmanage Match Release History](https://spaces.internet2.edu/display/COmanage/Home)
wiki page for the list of releases. We recommend using the latest release.

Here is an example (but please check the wiki page for the latest release number):

```
export COMANAGE_MATCH_VERSION=1.0.0
```

* Build the base COmanage Match image:

```
pushd comanage-match-base
docker build \
    --build-arg COMANAGE_MATCH_VERSION=${COMANAGE_MATCH_VERSION} \
    -t comanage-match-base:${COMANAGE_MATCH_VERSION}-1 .
popd
```

* Build an image for COmanage Match that uses basic authentication:

```
pushd comanage-match-basic-auth
docker build \
    --build-arg COMANAGE_MATCH_VERSION=${COMANAGE_MATCH_VERSION} \
    -t comanage-match:${COMANAGE_MATCH_VERSION}-basic-auth .
popd
```

* Build a local image of PostgreSQL for COmanage Match:

```
pushd comanage-match-postgres
docker build -t comanage-match-postgres .
popd
```

* Create a docker-compose.yml file:

```
version: '3.1'

services:

    comanage-match-database:
        image: comanage-match-postgres

    comanage-match:
        image: "comanage-match:${COMANAGE_MATCH_VERSION}-basic-auth"
        ports:
            - "80:80"
            - "443:443"
```

* Start the services:
```
docker-compose up -d
```

* Browse to port 443 on the host, for example `https://localhost/`. You will have to
  click through the warning from your browser about the self-signed certificate used
  for HTTPS.

* Click `Login` and when prompted enter `match.admin` as the username and `password`
for the password. 

* Visit the [COmanage wiki](https://spaces.at.internet2.edu/display/COmanage/Match+Platform+Configuration)
to learn how to create your first Matchgrid and begin using
the platform.

* To stop the services:
```
docker-compose stop
```

* To remove the containers and networks:
```
docker-compose down
```

### Important Notes
The instructions above are *not suitable for a production deployment* for two reasons:

1. The deployed services use default and easily guessed passwords.
2. No data is persisted. When the containers are destroyed so is your data.

## Next Steps
To evolve your COmanage Match deployment examine the documentation
in the [docs directory](./README.md).