Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Added deployment recipe for I2 TAP with PostgreSQL
Added deployment recipe documentation for the I2 TAP image with
PostgreSQL.
  • Loading branch information
skoranda committed May 29, 2019
1 parent c2eec34 commit f883177
Show file tree
Hide file tree
Showing 2 changed files with 297 additions and 0 deletions.
1 change: 1 addition & 0 deletions README.md
Expand Up @@ -67,6 +67,7 @@ Docker Swarm (the simple evaluation scenario above uses Docker Compose).

The following link to detailed instructions for a number of deployment scenarios.

* [COmanage Match using the Internet2 TAP image and PostgreSQL database](docs/internet2-postgresql.md)
* [COmanage Match using the Shibboleth SP and PostgreSQL database](docs/shibboleth-sp-postgresql.md)

## All Documentation
Expand Down
296 changes: 296 additions & 0 deletions docs/internet2-postgresql.md
@@ -0,0 +1,296 @@
<!--
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 for Internet2 TAP

Follow these steps to build and run the Internet2 TAP COmanage Match
image using PostgreSQL as the relational database.

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

* Clone this repository:

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

* 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+Match/Release+History)
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
```

* Define the shell variable `COMANAGE_MATCH_BASE_IMAGE_VERSION` to be the
version of the base image you are about to build:

```
export COMANAGE_MATCH_BASE_IMAGE_VERSION=1
```

* Build the base COmanage Match image:

```
pushd comanage-match/comanage-match-base
TAG="${COMANAGE_MATCH_VERSION}-${COMANAGE_MATCH_BASE_IMAGE_VERSION}"
docker build \
--build-arg COMANAGE_MATCH_VERSION=${COMANAGE_MATCH_VERSION} \
-t comanage-match-base:${TAG} .
popd
```

* Define the shell variable `COMANAGE_MATCH_I2_BASE_IMAGE_VERSION`
to be the version of the base I2 image you are about to build:

```
export COMANAGE_MATCH_I2_BASE_IMAGE_VERSION=1
```

* Build the base I2 image:

```
pushd comanage-match/comanage-match-internet2-tap-base
TAG="${COMANAGE_MATCH_I2_BASE_IMAGE_VERSION}"
docker build \
-t comanage-match-internet2-tap-base:$TAG .
popd
```

* Define the shell variable `COMANAGE_MATCH_I2_IMAGE_VERSION`
to be the version of the image you are about to build:

```
export COMANAGE_MATCH_I2_IMAGE_VERSION=1
```

* Build the I2 image:

```
pushd comanage-match/comanage-match-internet2-tap
TAG="${COMANAGE_MATCH_VERSION}-internet2-tap-${COMANAGE_MATCH_I2_IMAGE_VERSION}"
docker build \
--build-arg COMANAGE_MATCH_VERSION=${COMANAGE_MATCH_VERSION} \
--build-arg COMANAGE_MATCH_BASE_IMAGE_VERSION=${COMANAGE_MATCH_BASE_IMAGE_VERSION} \
--build-arg COMANAGE_MATCH_I2_BASE_IMAGE_VERSION=${COMANAGE_MATCH_I2_BASE_IMAGE_VERSION} \
-t comanage-match:$TAG .
popd
```

* Define the shell variable `COMANAGE_MATCH_POSTGRES_IMAGE_VERSION`
to be the version of the image you are about to build:

```
export COMANAGE_MATCH_POSTGRES_IMAGE_VERSION=1
```

* Build an image for PostgreSQL for COmanage Registry:

```
pushd comanage-match/comanage-match-postgres
TAG="${COMANAGE_MATCH_POSTGRES_IMAGE_VERSION}"
docker build \
-t comanage-match-postgres:${TAG} .
popd
```

* Initialize the Docker Swarm:

```
docker swarm init
```

* Create secrets for the database root password, the COmanage Match database
password, the HTTPS certificate (and CA signing chain) and private key files,
and the Shibboleth SP encryption certificate and private key files (be sure
to choose your own values and do not use the examples below):

```
echo "jPkrc3TUijfmT3vi1ZKw" | docker secret create postgres_password -
echo "ayFjKFHTre74A0k8k1mq" | docker secret create comanage_match_postgres_user_password -
echo "ayFjKFHTre74A0k8k1mq" | docker secret create comanage_match_database_user_password -
docker secret create https_cert_file fullchain.cert.pem
docker secret create https_privkey_file privkey.pem
docker secret create shibboleth_sp_encrypt_cert sp-encrypt-cert.pem
docker secret create shibboleth_sp_encrypt_privkey sp-encrypt-key.pem
```

* Create directories on the Docker engine host(s) for state files
and other files including the Shibboleth SP configuration files:

```
sudo mkdir -p /srv/docker/var/lib/postgresql/data
sudo mkdir -p /srv/docker/srv/comanage-match/local
sudo mkdir -p /srv/docker/etc/shibboleth
```

* Copy Shibboleth SP configuration files into place to be mounted
into the running container. Your Shibboleth SP configuration should
result in the primary identifier attribute you expect to be asserted by the SAML
IdP(s) to populate `REMOTE_USER` so that it can be read by COmanage Match.
A common choice is to populate `REMOTE_USER` with eduPersonPrincipalName, but
the details will depend on your SAML federation choices.


```
cp shibboleth2.xml /srv/docker/etc/shibboleth/
cp attribute-map.xml /srv/docker/etc/shibboleth/
cp saml-metadata.xml /src/docker/etc/shibboleth/
```

* Define a shell variable for the first COmanage Match platform
administrator, for example:

```
export COMANAGE_MATCH_ADMIN_USERNAME=karel.novak@my.org
```

The username should be the value you expect to be asserted by the
SAML IdP for the first platform administrator. The Shibboleth SP
configuration should be such that the value is populated into
`REMOTE_USER` where it will be read when the first platform
administrator logs into COmanage Match.

* Define a shell variable with the fully-qualified domain name for
the virtual host from which COmanage Match will be served. For
example

```
export COMANAGE_MATCH_VIRTUAL_HOST_FQDN=match.my.org
```

* Create a Docker Swarm services stack description (compose) file in YAML format:

```
version: '3.1'
services:
comanage-match-database:
image: comanage-match-postgres:${COMANAGE_MATCH_POSTGRES_IMAGE_VERSION}
volumes:
- /srv/docker/var/lib/postgresql/data:/var/lib/postgresql/data
environment:
- POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password
- COMANAGE_MATCH_POSTGRES_USER_PASSWORD_FILE=/run/secrets/comanage_match_postgres_user_password
secrets:
- postgres_password
- comanage_match_postgres_user_password
networks:
- default
deploy:
replicas: 1
comanage-match:
image: comanage-match:${COMANAGE_MATCH_VERSION}-internet2-tap-${COMANAGE_MATCH_I2_IMAGE_VERSION}
volumes:
- /srv/docker/srv/comanage-match/local:/srv/comanage-match/local
- /srv/docker/etc/shibboleth/shibboleth2.xml:/etc/shibboleth/shibboleth2.xml
- /srv/docker/etc/shibboleth/attribute-map.xml:/etc/shibboleth/attribute-map.xml
- /srv/docker/etc/shibboleth/saml-metadata.xml:/etc/shibboleth/saml-metadata.xml
environment:
- COMANAGE_MATCH_ADMIN_USERNAME=${COMANAGE_MATCH_ADMIN_USERNAME}
- COMANAGE_MATCH_DATASOURCE=Database/Postgres
- COMANAGE_MATCH_DATABASE_USER_PASSWORD_FILE=/run/secrets/comanage_match_database_user_password
- COMANAGE_MATCH_VIRTUAL_HOST_FQDN=${COMANAGE_MATCH_VIRTUAL_HOST_FQDN}
- HTTPS_CERT_FILE=/run/secrets/https_cert_file
- HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file
- SHIBBOLETH_SP_ENCRYPT_CERT=/run/secrets/shibboleth_sp_encrypt_cert
- SHIBBOLETH_SP_ENCRYPT_PRIVKEY=/run/secrets/shibboleth_sp_encrypt_privkey
secrets:
- comanage_match_database_user_password
- https_cert_file
- https_privkey_file
- shibboleth_sp_encrypt_cert
- shibboleth_sp_encrypt_privkey
networks:
- default
ports:
- "80:80"
- "443:443"
deploy:
replicas: 1
secrets:
comanage_match_database_user_password:
external: true
comanage_match_postgres_user_password:
external: true
postgres_password:
external: true
shibboleth_sp_encrypt_cert:
external: true
shibboleth_sp_encrypt_privkey:
external: true
https_cert_file:
external: true
https_privkey_file:
external: true
```

* Deploy the COmanage Match service stack:

```
docker stack deploy --compose-file comanage-match-stack.yml comanage-match
```

Since this is the first initialization of the containers it will take some
time for the database tables to be created. The Apache HTTP Server and
Shibboleth SP daemons will not be started until the entrypoint scripts
detect that the database has been initialized.

You may monitor the progress of the database container using

```
docker service logs -f comanage-match-database
```

and the progress of the COmanage Match container using

```
docker service logs -f comanage-match
```

* After the Apache HTTP Server has started browse to port 443 on the host.

* Click `Login` to initiate a SAML authentication flow. After authenticating at
the SAML IdP the Shibboleth SP should consume the SAML assertion and populate
`REMOTE_USER` with the value for the username for the first platform
administrator.

* Visit the [COmanage wiki](https://spaces.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 stack rm comanage-match
```

0 comments on commit f883177

Please sign in to comment.