From e52a7b9eb47738a27eb418788d40db14c723f75e Mon Sep 17 00:00:00 2001 From: lpaglione <682489+lpaglione@users.noreply.github.com> Date: Sun, 10 Nov 2019 17:43:04 -0500 Subject: [PATCH] Complete lesson --- _episodes/01-prep.md | 6 +-- _episodes/02-setupVariables.md | 77 +++++++++++++++++----------- _episodes/03-deploy.md | 92 ++++++++++++++++++++++++++++++++++ _episodes/04-signin.md | 55 ++++++++++++++++++++ index.md | 12 ++--- 5 files changed, 201 insertions(+), 41 deletions(-) create mode 100644 _episodes/03-deploy.md create mode 100644 _episodes/04-signin.md diff --git a/_episodes/01-prep.md b/_episodes/01-prep.md index 40955f0..1e86f03 100644 --- a/_episodes/01-prep.md +++ b/_episodes/01-prep.md @@ -1,7 +1,7 @@ --- title: "Installation Prep" -teaching: 25 -exercises: 10 +teaching: 0 +exercises: 15 questions: - "Question here" objectives: @@ -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. diff --git a/_episodes/02-setupVariables.md b/_episodes/02-setupVariables.md index d7a1b88..52324cd 100644 --- a/_episodes/02-setupVariables.md +++ b/_episodes/02-setupVariables.md @@ -1,7 +1,7 @@ --- title: "Setting up variables" -teaching: 25 -exercises: 10 +teaching: 0 +exercises: 30 questions: - "Question here" objectives: @@ -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` @@ -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: @@ -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) --- diff --git a/_episodes/03-deploy.md b/_episodes/03-deploy.md new file mode 100644 index 0000000..dbfe175 --- /dev/null +++ b/_episodes/03-deploy.md @@ -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) \ No newline at end of file diff --git a/_episodes/04-signin.md b/_episodes/04-signin.md new file mode 100644 index 0000000..e3ca07e --- /dev/null +++ b/_episodes/04-signin.md @@ -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) \ No newline at end of file diff --git a/index.md b/index.md index 5fb426f..1327f75 100644 --- a/index.md +++ b/index.md @@ -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)