diff --git a/README.md b/README.md index 3662227..78add8b 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/internet2-postgresql.md b/docs/internet2-postgresql.md new file mode 100644 index 0000000..7ddf962 --- /dev/null +++ b/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 +```