02-setupVariables.md

---
title: "Setting up variables"
teaching: 0
exercises: 30
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
workshopOverviewName: "COmanage Workshop: Managing Identities & Collaborations"
workshopOverviewURL: "https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md"
lessonOverviewName: "CO201 - Installing COmanage Using Docker Images"
lessonOverviewURL: "../index.md"
previousEpisodeName: "1. Installation Prep"
previousEpisodeURL: "/_episodes/01-prep.md"
nextEpisodeName: "3. Deploy COmanage"
nextEpisodeURL: "/_episodes/03-deploy.md"
---

# 2. Setting up variables

![Interactive system activity](/assets/img/hands-on-keyboard.png)

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; 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 [https://docs.docker.com/compose/compose-file/](https://docs.docker.com/compose/compose-file/)

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](https://github.com/Internet2/comanage-registry-docker/blob/master/docs/comanage-registry-common-environment-variables.md)

> _**NOTE** The TAP Docker images are quite general and can be used with any orchestration tool like Docker Swarm, Docker Compose, or Kubernetes. We are using Docker Swarm because it is the TAP reference and much simpler than Kubernetes._

If you run into challenges during this process, please put a yellow post-it note on your computer so that we can see that you need help.

## Look at the Docker services stack file

1. 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`

``` console
[training@registry1-private ~]$ 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:

```console
[training@registry1-private ~]$ more comanage-registry-stack.yml
```

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.

> When you are ready to move on, put the blue post-it note on your computer so that we can make sure to not move forward before everyone is ready.

## Create some Docker Swarm secrets

2. 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:

``` console
[training@registry1-private ~]$ 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. **IMPORTANT** replace the text `'password_one'` and `'password_two'` with passwords you make up.

``` console
[training@registry1-private ~]$ echo 'password_one' | docker secret create mysql_root_password -
pmdgsacd95nh9ufkntvqpd17z
[training@registry1-private ~]$ 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:

``` console
[training@registry1-private ~]$ 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
```

> When you are ready to move on, put the blue post-it note on your computer so that we can make sure to not move forward before everyone is ready.

## 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. Let's start out by taking a look at the services stack file in more depth. First start editing the file:

``` console
[training@registry1-private ~]$ 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

> Note to instructor: This class does not have learning Docker services stack files or Nano as one of its goals. Be prepared to answer questions about Nano or the Docker services stack file structure and sub sections if they arise, particularly if they are blocking participants from moving forward to the next step of the lesson. Though, keep these answers targeted to the task at hand, referring participants to the references for [Docker Compose Files](https://docs.docker.com/compose/compose-file/) and [nano](https://www.howtogeek.com/howto/42980/the-beginners-guide-to-nano-the-linux-command-line-text-editor/) if there are additional questions. Additional questions can also be addressed at the break.

4. 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](https://github.com/Internet2/comanage-registry-docker/blob/master/docs/comanage-registry-common-environment-variables.md). Only a subset of these variables are configured here:

* **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

``` yaml
# 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

``` yaml
- 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:

```console
[training@registry1-private ~]$ more comanage-registry-stack.yml
```

> When you are ready to move on, put the blue post-it note on your computer so that we can make sure to not move forward before everyone is ready.

---

NEXT SECTION: [3. Deploy COmanage](/_episodes/03-deploy.md)

PREVIOUS SECTION: [1. Installation Prep](/_episodes/01-prep.md)

---

LESSON OVERVIEW: [CO201 - Installing COmanage Using Docker Image](../index.md)

WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md)
	---
	title: "Setting up variables"
	teaching: 0
	exercises: 30
	questions:
	- "Question here"
	objectives:
	- "List the objectives"
	keypoints:
	- "List the key takeaways for the episode"
	workshopOverviewName: "COmanage Workshop: Managing Identities & Collaborations"
	workshopOverviewURL: "https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md"
	lessonOverviewName: "CO201 - Installing COmanage Using Docker Images"
	lessonOverviewURL: "../index.md"
	previousEpisodeName: "1. Installation Prep"
	previousEpisodeURL: "/_episodes/01-prep.md"
	nextEpisodeName: "3. Deploy COmanage"
	nextEpisodeURL: "/_episodes/03-deploy.md"
	---

	# 2. Setting up variables

	![Interactive system activity](/assets/img/hands-on-keyboard.png)

	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; 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 [https://docs.docker.com/compose/compose-file/](https://docs.docker.com/compose/compose-file/)

	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](https://github.com/Internet2/comanage-registry-docker/blob/master/docs/comanage-registry-common-environment-variables.md)

	> _NOTE The TAP Docker images are quite general and can be used with any orchestration tool like Docker Swarm, Docker Compose, or Kubernetes. We are using Docker Swarm because it is the TAP reference and much simpler than Kubernetes._

	If you run into challenges during this process, please put a yellow post-it note on your computer so that we can see that you need help.

	## Look at the Docker services stack file

	1. 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`

	``` console
	[training@registry1-private ~]$ 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:

	```console
	[training@registry1-private ~]$ more comanage-registry-stack.yml
	```

	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.

	> When you are ready to move on, put the blue post-it note on your computer so that we can make sure to not move forward before everyone is ready.

	## Create some Docker Swarm secrets

	2. 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:

	``` console
	[training@registry1-private ~]$ 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. IMPORTANT replace the text `'password_one'` and `'password_two'` with passwords you make up.

	``` console
	[training@registry1-private ~]$ echo 'password_one' \| docker secret create mysql_root_password -
	pmdgsacd95nh9ufkntvqpd17z
	[training@registry1-private ~]$ 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:

	``` console
	[training@registry1-private ~]$ 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
	```

	> When you are ready to move on, put the blue post-it note on your computer so that we can make sure to not move forward before everyone is ready.

	## 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. Let's start out by taking a look at the services stack file in more depth. First start editing the file:

	``` console
	[training@registry1-private ~]$ 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

	> Note to instructor: This class does not have learning Docker services stack files or Nano as one of its goals. Be prepared to answer questions about Nano or the Docker services stack file structure and sub sections if they arise, particularly if they are blocking participants from moving forward to the next step of the lesson. Though, keep these answers targeted to the task at hand, referring participants to the references for [Docker Compose Files](https://docs.docker.com/compose/compose-file/) and [nano](https://www.howtogeek.com/howto/42980/the-beginners-guide-to-nano-the-linux-command-line-text-editor/) if there are additional questions. Additional questions can also be addressed at the break.

	4. 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](https://github.com/Internet2/comanage-registry-docker/blob/master/docs/comanage-registry-common-environment-variables.md). Only a subset of these variables are configured here:

	* 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

	``` yaml
	# 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

	``` yaml
	- 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:

	```console
	[training@registry1-private ~]$ more comanage-registry-stack.yml
	```

	> When you are ready to move on, put the blue post-it note on your computer so that we can make sure to not move forward before everyone is ready.

	---

	NEXT SECTION: [3. Deploy COmanage](/_episodes/03-deploy.md)

	PREVIOUS SECTION: [1. Installation Prep](/_episodes/01-prep.md)

	---

	LESSON OVERVIEW: [CO201 - Installing COmanage Using Docker Image](../index.md)

	WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md)