Skip to content

Commit

Permalink
Complete lesson
Browse files Browse the repository at this point in the history
  • Loading branch information
lpaglione committed Nov 10, 2019
1 parent 962f318 commit e52a7b9
Show file tree
Hide file tree
Showing 5 changed files with 201 additions and 41 deletions.
6 changes: 3 additions & 3 deletions _episodes/01-prep.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Installation Prep"
teaching: 25
exercises: 10
teaching: 0
exercises: 15
questions:
- "Question here"
objectives:
Expand All @@ -26,7 +26,7 @@ For this lesson, we will be installing COmanage from a Docker image onto a virtu

## VM & user assignments

At your station is a Workshop Reference Document that lists a virtual machine number and a list of three "users" that you will be using throughout the workshop as we explore COmanage. Each one of us has a different set.
At your station is a [Workshop Reference Document] that lists a virtual machine number and a list of three "users" that you will be using throughout the workshop as we explore COmanage. Each one of us has a different set.

Also on this Document is the password that we will be using for the workshop. This password will be used for every instance where a password is needed.

Expand Down
77 changes: 47 additions & 30 deletions _episodes/02-setupVariables.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Setting up variables"
teaching: 25
exercises: 10
teaching: 0
exercises: 30
questions:
- "Question here"
objectives:
Expand All @@ -28,6 +28,8 @@ For the workshop, we will be using a file that has already been partially config

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

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`
Expand All @@ -51,6 +53,8 @@ we can see the content of this file by using the `more` command:

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.

> 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:
Expand Down Expand Up @@ -97,59 +101,72 @@ it2udfg969bpntn59qu8k7ifs shibboleth_sp_signing_cert
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

## Sign into your virtual machine

You will be using SSH to sign into your virtual machine. 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.
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.

1. SSH to the [AWS bastion host](https://aws.amazon.com/blogs/security/tag/bastion-host/) by typing the following command:
3. Let's start out by taking a look at the stack file in more depth. First start editing the file:

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

You will use the training session password when requested. As a reminder, you can find the password on the Workshop Reference Document.
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.)_:

2. Once on the bastion host, SSH into the virtual machine that you will be using for the workshop. Refer to the Workshop Reference Document to see the name of your virtual host. You will replace the letter 'N' in the command below, with the number for your virtual machine.
* database: We will be using a MariaDB relational database
* registry: This is the COmanage Registry
* ldap: An OpenLDAP slapd LDAP directory/server

``` console
$ ssh registryN-private
```
> 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.
> 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.
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:

## Take a look at Docker
* **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.

3. The docker files are already available to you, so you can run a few docker commands to check them.
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.

First we'll see what docker nodes are available:
5. Add your CMP (Platform) Administrator

``` console
[training@registry1-private ~]$ docker node ls
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
8tuwrbfdci97tfn9nqoinic0o * registry1-private.comanage.incommon.training Ready Active Leader 19.03.4
```
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

You can also see the list of containers that are available by running the docker ps command. (NOTE, there shouldn't be any Docker containers because we haven't set them up yet. This command will confirm that this is true.)
``` yaml
# include the given name for your CMP Administrator without quotes
- COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=

``` console
[training@registry1-private ~]$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
# 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=
```
_**NOTE**: You can also use `sudo` without a password, but you probably will not need it in this session. For example,_
The last value (the username) is the eduPersonPrincipalName the IdP will assert (it uses scope comanage.incommon.training in this training environment).
``` console
[training@registry1-private ~]$ sudo /usr/bin/whoami
root
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: [2. Setting up variables](/_episodes/02-setupVariables.md)
NEXT SECTION: [3. Deploy COmanage](/_episodes/03-deploy.md)

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

---

Expand Down
92 changes: 92 additions & 0 deletions _episodes/03-deploy.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
---
title: "Deploy COmanage"
teaching: 0
exercises: 10
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: "2. Setting up variables"
previousEpisodeURL: "/_episodes/02-setupVariables.md"
nextEpisodeName: "4. First sign in"
nextEpisodeURL: "/_episodes/04-signin.md"
---

# 3. Deploy COmanage

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

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

## Deploy the services

Deploy the services using the following command.

``` console
[training@registry1-private ~]$ docker stack deploy --compose-file comanage-registry-stack.yml comanage
Creating network comanage_default
Creating service comanage_database
Creating service comanage_registry
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:

**Review what Docker stacks are available**

``` console
[training@registry1-private ~]$ docker stack ls
NAME SERVICES ORCHESTRATOR
comanage 3 Swarm
```

**Review what Docker services are running**

``` console
[training@registry1-private ~]$ docker service ls
ID NAME MODE REPLICAS IMAGE PORTS
ypl33s0036a1 comanage_database replicated 1/1 mariadb:10.4.8
95316c0h0x5s comanage_ldap replicated 1/1 sphericalcowgroup/comanage-registry-slapd:2 *:389->389/tcp
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**

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

``` console
[training@registry1-private ~]$ docker service logs comanage_registry
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | 2019-11-10 22:11:31,903 CRIT Set uid to user 0
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | 2019-11-10 22:11:31,905 INFO supervisord started with pid 1
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | 2019-11-10 22:11:32,908 INFO spawned: 'shibd' with pid 8
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | 2019-11-10 22:11:32,909 INFO spawned: 'apache2' with pid 9
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | Created directory /srv/comanage-registry/local/Config
comanage_registry.1.ibnk0b81b05q@registry1-private.comanage.incommon.training | Created directory /srv/comanage-registry/local/Plugin
...
```

---

NEXT SECTION: [4. First sign in](/_episodes/04-signin.md)

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)
55 changes: 55 additions & 0 deletions _episodes/04-signin.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
---
title: "First Sign In"
teaching: 0
exercises: 5
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: "3. Deploy COmanage"
previousEpisodeURL: "/_episodes/03-deploy.md"
nextEpisodeName:
nextEpisodeURL:
---

# 4. First Sign in

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

You're now ready to launch COmanage!

## Browse to your node

1. Launch a browser window and go to the URL for your training site. Replace the `N` in the URL below for the address of your registry

https://registryN.comanage.incommon.training

For example, if your VM is number 1, you should use the URL

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) 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.

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.

---

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

---

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)
12 changes: 4 additions & 8 deletions index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,17 +21,13 @@ In this lesson, you will learn how to install COmanage and configure it for basi
Time | Section | Description
---- | ------- | -----------
  | [Setup](/setup/) | Prepare for the lesson
00:35 | [1. Identifiers](/_episodes/01-identifiers) | Learn the importance of identifiers within COmanage and their use when connecting to other systems as sources or for provisioning. Understand identifier formats and how to make identifier assignments to `CO Persons`:gear:
00:20 | [2. `CO Services`:gear: ](/_episodes/02-coServices.md) | Configure a group of services that can be accessed by those in your `CO`:gear:
00:30 | [3. Authenticators](/_episode/03-authenticators) | Learn how authenticators work to enable authenticated access to services. Understand what kinds are supported, and how alternate forms, like SSH keys, are supported.
00:15 | [1. Installation Prep](/_episodes/01-prep.md) | Get familiar with the process and understand what will be different when you install in your own environment.
00:30 [2. Setting up variables](/_episodes/02-setupVariables.md) | Using the stack file (compose file), set variables that you will need for initial configuration of COmanage.
00:10 [3. Deploy COmanage](/_episodes/03-deploy.md) | Deploy COmanage on your virtual machine
00:05 [4. First sign in](/_episodes/04-signin.md) | Sign into COmanage.

_The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor._

1. [1. Installation Prep](/_episodes/01-prep.md) | Get familiar with the process and understand what will be different when you install in your own environment.
2. [2. Setting up variables](/_episodes/02-setupVariables.md) | Using the stack file (compose file), set variables that you will need for initial configuration of COmanage.
3. [3. Deploy COmanage](/_episodes/03-deploy.md) | Deploy COmanage on your virtual machine
4. [4. First sign in](/_episodes/04-signin.md) | Sign into COmanage.

---

PREVIOUS LESSON: [CO101 - Getting to Know COmanage](https://github.internet2.edu/lpaglione/COmg-CO101-intro/blob/master/index.md)
Expand Down

0 comments on commit e52a7b9

Please sign in to comment.