2. Setting up variables

In this section we will be updating the Docker services stack (compose) file so that your instance of COmanage is customized for your use. Our goal is to increase your familiarity with the process that you will need to configure COmanage when deploying your own installation.

Scratching the surface

This installation lesson just scratches the surface of learning how to install COmanage. It is designed to provide some exposure to things that you will need to do when installing COmanage. These instructions also make choices to use specific tools for the installation, although others can be used for this purpose. Some notes:

• Using Docker: Our goal is not to teach Docker. But if you are interested in the format of the services stack (compose) file, we suggest taking a look at this resource about Docker Compose Files.
• Using Nano: Likewise, the instructions below provide directions for editing files using Nano. This nano reference will be useful if you seek more information.
• Configuring COmanage variables: For the workshop, we will be using a file that has already been partially configured for you. Though, a full list of configuration variables and the file format can be found at COmanage Registry Docker Environment Variables

Look at the Docker services stack file

1. Explore the services stack file

In the home directory of your training account you will find the Docker Swarm services stack (compose) file. You can see it if you use the list command, ls

ls

comanage-registry-stack.yml

The services stack file is used to deploy 3 services:

• A MariaDB relational database
• An OpenLDAP slapd LDAP directory/server
• COmanage Registry

we can see the content of this file by using the more command:

more comanage-registry-stack.yml

version: '3.7'

services:
    database:
        image: mariadb:10.4.8
        volumes:
            - /srv/docker/var/lib/mysql:/var/lib/mysql
        environment:
            - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/mysql_root_password
            - MYSQL_DATABASE=registry
            - MYSQL_USER=registry_user
            - MYSQL_PASSWORD_FILE=/run/secrets/mysql_registry_user_password
        secrets:
            - mysql_root_password
            - mysql_registry_user_password
        deploy:
            replicas: 1
        logging:
            driver: journald
            options:
                tag: "mariadb-{{.Name}}"

    registry:
        image: tier/comanage:3.2.2-20191108
        volumes:
            - /srv/docker/srv/comanage-registry/local:/srv/comanage-registry/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/idp-metadata.xml:/etc/shibboleth/idp-metadata.xml
            - /srv/docker/etc/httpd/conf.d/000-comanage.conf:/etc/httpd/conf.d/000-comanage.conf
        environment:
--More--(26%)

Use the space bar on your keyboard to scroll through the document. The services stack file is NOT ready to be used as is. You must complete two tasks to prepare them.

Create some Docker Swarm secrets

2. Set the passwords

Most secrets needed by the Docker images such as the email SMTP server password and SAML signing and encryption keys have been pre-populated and stored for you using the Docker Swarm secrets mechanism. You can see the list of secrets by running the following command:

docker secret ls

ID                          NAME                                       DRIVER              CREATED             UPDATED
3p0ap0d7kve8rrdanqfhf6fvt   comanage_registry_email_account_password                       3 days ago          3 days ago
vqdwbhnnalvpto86uuf37yxe2   olc_root_dn_password                                           3 days ago          3 days ago
yom7jijnnitg6an72kwptf8ii   olc_root_pw                                                    3 days ago          3 days ago
lewv1ma6aw6irlwpl7bse96l8   shibboleth_sp_encrypt_cert                                     3 days ago          3 days ago
ff8ieqk2hshg9uuxrhvysgfxs   shibboleth_sp_encrypt_privkey                                  3 days ago          3 days ago
it2udfg969bpntn59qu8k7ifs   shibboleth_sp_signing_cert                                     3 days ago          3 days ago
ym6xcjw0bn10zl2k5hcik77xv   shibboleth_sp_signing_privkey                                  3 days ago          3 days ago

You will need to create and store as Docker Swarm secrets two (2) additional (strong!) passwords for accessing the MariaDB relational database:

• the root password for MariaDB
• the password used for connecting to the registry database (which will be automatically created for them)

To store these secrets use the docker secret create command along with the echo and pipe |commands.

echo 'password_one' | docker secret create mysql_root_password -

pmdgsacd95nh9ufkntvqpd17z

echo 'password_two' | docker secret create mysql_registry_user_password -

s8rrhhf3ne04iiphcbzi77q22

Note that the output is just a type of hash used as an ID for the secret. The actual secret is encrypted and only decrypted and made available to images that need it when they are instantiated to become running containers.

Make sure that the passwords have been added by re-running the command from earlier. (The new lines are highlighted in the sample output below.):

docker secret ls

ID                          NAME                                       DRIVER              CREATED             UPDATED
3p0ap0d7kve8rrdanqfhf6fvt   comanage_registry_email_account_password                       3 days ago          3 days ago
s8rrhhf3ne04iiphcbzi77q22   mysql_registry_user_password                                   2 minutes ago       2 minutes ago
pmdgsacd95nh9ufkntvqpd17z   mysql_root_password                                            4 minutes ago       4 minutes ago
vqdwbhnnalvpto86uuf37yxe2   olc_root_dn_password                                           3 days ago          3 days ago
yom7jijnnitg6an72kwptf8ii   olc_root_pw                                                    3 days ago          3 days ago
lewv1ma6aw6irlwpl7bse96l8   shibboleth_sp_encrypt_cert                                     3 days ago          3 days ago
ff8ieqk2hshg9uuxrhvysgfxs   shibboleth_sp_encrypt_privkey                                  3 days ago          3 days ago
it2udfg969bpntn59qu8k7ifs   shibboleth_sp_signing_cert                                     3 days ago          3 days ago
ym6xcjw0bn10zl2k5hcik77xv   shibboleth_sp_signing_privkey                                  3 days ago          3 days ago

Configure your COmanage Platform Administrator

In the last section, you wrote down the three users that you will be working with throughout this workshop. Here we will edit the details of the services stack file so that when the COmanage Registry container is started it will bootstrap the necessary account details for your first Platform Administrator.

3. Explore the services stack file

Let’s start out by taking a look at the services stack file in more depth. First start editing the file:

nano comanage-registry-stack.yml

This file has two sections services and secrets.

In the services section there are three services that are configured (use ctrl-v to get to the next page and ctrl-y to get to the previous page. Other commands can be seen at the bottom of the nano window.):

• database: We will be using a MariaDB relational database
• registry: This is the COmanage Registry
• ldap: An OpenLDAP slapd LDAP directory/server

4. Explore the fields you will customize

Review the environment variables used to configure the COmanage Registry Docker image when it is instantiated as a running container or service. A full reference of enviornment variables can be found at the COmanage Registry Docker Environment Variables guide. Only a subset of the possible variables are included in this copy of the services stack file:

• Registry Administrator: The Given Name, Family Name, and Username are needed to bootstrap the account for the person who will sign into the Registry as the first Platform Administrator as soon as it is launched. These three fields are blank; you will to fill them with the details for the user that you have selected to be your Platform Administrator.
• Database: These variables are needed to allow the Registry to connect to the MariaDB database deployed as part of the service stack. When you install COmanage in your own environment, you may be connecting to an existing database rather than one being deployed at the same time as the Registry (as we are doing here.) In that situation, you would include information for your own database.
• Email: COmanage is most often deployed and configured to send emails to users, for example, during enrollments. The services stack file has been preconfigured with the details of the SMTP server that will be used during the workshop.

Note that the services stack file itself does not include any secrets such as passwords, and so it is suitable for being managed in a standard configuration repository. In each case where a secret is needed, the actual secret is passed to the running container by the Docker Swarm.

5. Add your Platform Administrator

In the previous section, you wrote down three users that you will be working with during the workshop. The first of these will be the Platform Administrator that will be able to sign in once COmanage is running. You will add the user’s information in the environment section of the registry section of the file. The variable names are already in the file; you only need to fill in the values

# include the given name for your CMP Administrator without quotes
- COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=

# include the family name for your CMP Administrator without quotes
- COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=

# include an ePPN for your CMP Administrator without quotes 
- COMANAGE_REGISTRY_ADMIN_USERNAME=

The username is the identifier COmanage Registry expects to read from the Apache REMOTE_USER environment variable after the user authenticates. The TAP COmanage Registry Docker image uses SAML and the Shibboleth service provider (SP) and the workshop deployment is configured so that the eduPersonPrincipalName for the authenticated user populates REMOTE_USER. The SAML identity provider (IdP) used during the workshop adds the scope comanage.incommon.training to the username to create the eduPersonPrincipalName.

As an example, if your CMP Administrator was Carla Woo, your values would be

- COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=Carla
- COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=Woo
- COMANAGE_REGISTRY_ADMIN_USERNAME=carla.woo@comanage.incommon.training

Once you have made these changes, exit nano (ctrl-x), and when prompted, indicate that you would like to save the file (Y). Save the file with the same name (comanage-registry-stack.yml). This action will return you to the command line. If you would like, you can confirm that the changes were made by using the command we used earlier:

more comanage-registry-stack.yml