Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
A few edits for clarity and consistency 
A few edits for clarity and consistency. Removed the term 'CMP' and
consistently used Platform Administrator since CMP is more generic--it
usually stands for Collaboration Management Platform.
@skoranda
skoranda committed Nov 11, 2019
1 parent c580ee5 commit e2ee82f
Showing 3 changed files with 43 additions and 29 deletions.
43 changes: 23 additions & 20 deletions _episodes/02-setupVariables.md
View file
@@ -22,15 +22,15 @@ nextEpisodeURL: "/_episodes/03-deploy.md"

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

In this section we will be updating the Docker stack (compose) file so that your instance of COmanage is customized for your use. Our goal is to increase your familiarity with the variables that you might need to configure COmanage when doing your own installation; we do not have a goal to teach Docker. But if you are interested in the format of the stack (compose) file, we suggest taking a look at [https://docs.docker.com/compose/compose-file/](https://docs.docker.com/compose/compose-file/)
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 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 easier than Kubernetes._
> _**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 stack file
## 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`

@@ -39,7 +39,7 @@ If you run into challenges during this process, please put a yellow post-it note
comanage-registry-stack.yml
```

The stack file is used to deploy 3 services:
The services stack file is used to deploy 3 services:

- A MariaDB relational database
- An OpenLDAP slapd LDAP directory/server
@@ -51,13 +51,13 @@ we can see the content of this file by using the `more` command:
[training@registry1-private ~]$ more comanage-registry-stack.yml
```

Use the space bar on your keyboard to scroll through the document. The stack file is NOT ready to be used as is. You must complete two tasks to prepare them.
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 images have been pre-populated for you. You can see the list of secrets by running the following command:
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
@@ -71,12 +71,12 @@ it2udfg969bpntn59qu8k7ifs shibboleth_sp_signing_cert
ym6xcjw0bn10zl2k5hcik77xv shibboleth_sp_signing_privkey 3 days ago 3 days ago
```

Here there are most of the passwords that the services will need, but you will need two additional (good!) ones for using MariaDB:
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 set these passwords, you will copy them into the docker secret file using the `echo` and pipe `|`commands to append these new passwords to the list. **IMPORTANT** replace the text `'password_one'` and `'password_two'` with your passwords.
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 -
@@ -85,7 +85,8 @@ pmdgsacd95nh9ufkntvqpd17z
s8rrhhf3ne04iiphcbzi77q22
```

In each case, the response is an encrypted form of the password that Docker will use when configured to do so.
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:

@@ -107,9 +108,10 @@ ym6xcjw0bn10zl2k5hcik77xv shibboleth_sp_signing_privkey
## 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 set up the CMP (Platform) Administrator so that we are able to log into COmanage once it is created by editing the stack file.
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 stack file in more depth. First start editing the file:
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
@@ -121,17 +123,18 @@ This file has two sections `services` and `secrets`. In the `services` section t
* registry: This is the COmanage Registry
* ldap: An OpenLDAP slapd LDAP directory/server

> Note to instructor: This class does not have learning Docker stack files or Nano as one of its goals. Be prepared to answer questions about Nano or the Docker 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.
> 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 COmanage environment variables. 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:
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 for the person who will sign into the Registry as soon as it is launched. These three fields are blank; you will fill them in with the person that you have selected to be your CMP Admin.
* **Database**: These variables are needed to allow the Registry to sign into the MariaDB database that we are installing. When you install COmanage in your own environment, you may be connecting to an existing database rather than one being installed 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 can be configured to send emails to users, for example, for notifications. The file currently has a simple gmail account configured to send emails for the training purposes.
* **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.

In each case where a password is needed, we are using a password that is stored in the Docker secrets that we reviewed (and added to) earlier. The two passwords that you created in step 2 above are referenced here in the `database` section of the file.
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 CMP (Platform) Administrator
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

@@ -146,7 +149,7 @@ In the previous section, you wrote down three users that you will be working wit
- COMANAGE_REGISTRY_ADMIN_USERNAME=
```

The last value (the username) is the eduPersonPrincipalName the IdP will assert (it uses scope comanage.incommon.training in this training environment).
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

@@ -174,4 +177,4 @@ 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)
WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md)
21 changes: 16 additions & 5 deletions _episodes/03-deploy.md
View file
@@ -22,7 +22,7 @@ nextEpisodeURL: "/_episodes/04-signin.md"

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

With our Stack (Compose) File all set, we are ready to spin up the services!
With our services stack (compose) file all set, we are ready to spin up the services!

## Deploy the services

@@ -38,7 +38,7 @@ Creating service comanage_ldap

The three services defined in our file have been created.

Since we are using an AWS load balancer, it will take about a minute to "see" that the note is healthy and ready for traffic. In the meantime, let's check on the service:
The virtual machine you are using during the workshop is deployed "behind" an Amazon AWS application load balancer (ALB) and it may take about a minute for the ALB to "see" that the COmanage Registry service is healthy and to route traffic to it. In the meantime, let's check on the service:

**Review what Docker stacks are available**

@@ -58,15 +58,15 @@ ypl33s0036a1 comanage_database replicated 1/1
wniftw1nguw1 comanage_registry replicated 1/1 sphericalcowgroup/comanage-registry:hotfix-3.2.x-shibboleth-sp-4 *:80->80/tcp
```

**Review the tasks for the services**
**Review the tasks for the COmanage Registry service**

``` console
[training@registry1-private ~]$ docker service ps comanage_registry
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
ibnk0b81b05q comanage_registry.1 sphericalcowgroup/comanage-registry:hotfix-3.2.x-shibboleth-sp-4 registry1-private.comanage.incommon.training Running Running 8 minutes ago
```

**Review the logs for the services**
**Review the logs for the COmanage Registry services**

``` console
[training@registry1-private ~]$ docker service logs comanage_registry
@@ -79,6 +79,17 @@ comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training
...
```

You may continuously follow the log files for the service by adding the `-f` flag to the previous command:

``` console
[training@registry1-private ~]$ docker service logs -f comanage_registry
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | [Mon Nov 11 15:06:45.621935 2019] [core:notice] [pid 9] AH00094: Command line: 'apache2 -D FOREGROUND'
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | 10.255.0.2 - "" [11/Nov/2019:15:06:53 +0000] "GET /registry/ HTTP/1.1" 200 4108 "-" "ELB-HealthChecker/2.0"
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | 10.255.0.2 - "" [11/Nov/2019:15:06:55 +0000] "GET /registry/ HTTP/1.1" 200 4108 "-" "ELB-HealthChecker/2.0"
...
```


> 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.
---
@@ -91,4 +102,4 @@ PREVIOUS SECTION: [2. Setting up variables](/_episodes/02-setupVariables.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)
WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md)
8 changes: 4 additions & 4 deletions _episodes/04-signin.md
View file
@@ -22,7 +22,7 @@ nextEpisodeURL:

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

You're now ready to launch COmanage!
You're now ready to log into COmanage Registry as the first Platform Administrator!

## Browse to your node

@@ -36,11 +36,11 @@ https://registry1.comanage.incommon.training

## Log in

You will need to login in as the CMP Administrator that you set up in the Stack File. (This is the only user configured to use the system at the moment!) Enter this user's username (ePPN - firstName.lastName) and the training password (check your Workshop Reference Document if you don't remember the password.)
You will need to login in as the Platform Administrator that you set up in the services stack file. (This is the only user configured to use the system at the moment!) Enter this user's username and the training password (check your Workshop Reference Document if you don't remember the password.)

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.

On the attribute release notice that the identity provider (Our Identity Provider) puts up, select the middle choice, "Ask me again if information to be provided to this service changes."
On the attribute release consent form that the identity provider (Our Identity Provider) displays, select the middle choice, "Ask me again if information to be provided to this service changes."

When you have successfully signed in (!), put the blue post-it note on your computer so that we can make sure to not move forward before everyone is ready.

@@ -54,4 +54,4 @@ LESSON OVERVIEW: [CO201 - Installing COmanage Using Docker Image](../index.md)

NEXT LESSION: **BREAK**

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

0 comments on commit e2ee82f

Please sign in to comment.