Merge pull request #22 from IBM/workshop-doc-updates

eric-simpson · web-flow · commit 0e57f42cd30f · 2024-01-18T14:07:55.000-05:00
workshop doc updates
diff --git a/docs/workshop/01_admin.md b/docs/workshop/01_admin.md
@@ -1,20 +1,33 @@
 
-## One-Time (Administrator) Preparation
+## Review Administrator Preparation
 
 These set-up steps have already been run for you.  They are documented here for your awareness and education and will be useful when you want to set up Merlin in your own environment.
 
-After your Infrastructure has been installed/configured, but before you can actually start using Merlin:
-
-1. Configure git for Source Configuration Management  
-2. (If needed) migrate source from physical files -> IFS -> git repo
-3. IBM i Integration in Merlin
-4. Create Application definition - source and object libraries
+1. Setup git
+   1. Configure git repository for Source Configuration Management  
+   2. Load ARCAD-EXAMPLE source into git repository (in general, if necessary migrate source from physical files -> IFS -> git repository)
+   3. Generate SSH key pair for use from Merlin IDE, git repository, and IBM i userid
+   4. Configure webhook for Arcad builder
+2. Create ide and cicd projects in Merlin
+3. Install IDE tool into ide project, install CICD tool into cicd project
+4. Create Merlin users, e.g. `lparXuserY`
+5. Add Inventory for each IBM i hostname
+6. Add Merlin users and inventory into group
+7. Add group to project
+8. For each user, create credentials with IBM i userid and password, create template using credential and inventory
+9. Run IBM i configuration for Merlin
+10. In CICD tool: 
+    1. initialize internal Jenkins server
+    2. add users
+    3. add jenkins credential for IBM i user id to access ARCAD build server,
+    4. enable ARCAD integration for jenkins server
+<!--4. Create Application definition - source and object libraries-->
 
 ### Configuring of Source Control Management
 Modern application development presupposes good source control that can enable best practices.
-Git is the most popular source code which can be used to drived your CI/CD pipeline suing web-hooks that can trigger builds when certain events happen in git. There are many different web interfaces to git that help automate the development process.  These include Github, Gitlab and Gitbucket.  If this is hosted outside of Merlin than the git hook needs some firewall configuration to access the builders running in Merlin.  The sandobx environment is configured with Gitbucket running on the IBM i.  This means that no new server is required and everything runs within the same secure network.  The source for the demo the repository already contains the sample application source and the git hook is configured.  Arcad products clone source from the git repository when doing builds on the IBM i and the user profile launching this needs to have the ssh key set up to access the git repository.  This also taken care of the sandbox environmetn.
+Git is the most popular source code which can be used to drive your CI/CD pipeline using web-hooks that can trigger builds when certain events happen in git. There are many different web interfaces to git that help automate the development process.  These include Github, Gitlab and Gitbucket.  If this is hosted outside of Merlin than the web-hook needs some firewall configuration to access the builders running in Merlin.  The sandbox environment is configured with Gitbucket running on the IBM i.  This means that no new server is required and everything runs within the same secure network.  The source for the demo the repository already contains the sample application source and the web-hook is configured.  Arcad products clone source from the git repository when doing builds on the IBM i and the user profile launching this needs to have the ssh key set up to access the git repository.  This also taken care of the sandbox environment.
 
-### IBM i integration in Merlin
+### IBM i configuration for Merlin
 
 <!-- panels:start -->
 
@@ -23,10 +36,10 @@ Git is the most popular source code which can be used to drived your CI/CD pipel
 6 actions on IBM i performed sequentially from Merlin by the Administrator: 
 
 1. Enable ansible (_this is the automation framework used for the subsequent steps_)
-2. Validate PTF level (_ensures that the IBM i is a the prequisite software level_)
-3. Install certificates (_are required to have encrypted HTTPS communications_)
+2. Validate PTF level (_ensures that the IBM i is at the prerequisite software level_)
+3. Install certificates (_required to have encrypted HTTPS communications_)
 4. Enable IBM i Developer (_configures IBM i backend for Merlin_)
-5. Enable remote debugger (_configures IBM i backend for the debugger_)
+5. Enable debug service (_configures IBM i backend for the debugger_)
 6. Enable Arcad (_install Arcad solutions on the target IBM i_)
 
 <!-- div:right-panel -->
@@ -37,16 +50,17 @@ Git is the most popular source code which can be used to drived your CI/CD pipel
 
 ---
 
-### Creation of an Arcad Application
-
+<!--### Creation of an Arcad Application
+-->
 <!-- panels:start -->
 
 <!-- div:left-panel -->
 
-The Arcad application has already been created for you.  
+<!--The Arcad application has already been created for you.  
 When doing this for your own application this can easily be done from with the IDE as an action on the IBM i project or alternatively it can be done through Arcad green screen commands. 
+-->
 <!-- div:right-panel -->
 
-![](01/from_merlin.png)
-
+<!--![](01/from_merlin.png)
+-->
 <!-- panels:end -->
diff --git a/docs/workshop/02_start.md b/docs/workshop/02_start.md
@@ -1,20 +1,20 @@
 
-## Preparation: Developer Authentication (SSH)
+<!--## Preparation: Developer Authentication (SSH)
 
 Result: Source files migrated to git
 
 ![](02/repo_a.png)
 
 ![](02/repo_b.png)
-
+-->
 ## Connection to Merlin & Platform overview 
 
 <!-- panels:start -->
 
 <!-- div:left-panel -->
 
-* URL will be provided to you.
-* `teamX` / `Passw0rd!` (X from 1 to 12)
+* URL to Merlin landing page will be provided to you.
+* Merlin userid and password will be provided to you.
 
 <!-- div:right-panel -->
 
@@ -30,9 +30,7 @@ Result: Source files migrated to git
 
 ### Landing page
 
-Accessible services granted by Merlin administrators.
-
-Here, teamX users (group "techxchange") have access to projects "cicd" and "merlin-tools". "cicd" and "merlin-tools" have provisioned services: IBM i CI/CD and and IBM i Developer, respectively.
+Here, users have access to projects "cicd" and "ide" which have provisioned services: IBM i CI/CD and IBM i Developer (as configured by Merlin admin).
 
 Isolation can be done by projects, with different authorizations & roles on resources.
 
@@ -75,7 +73,7 @@ Merlin can provision IBM i VM for a project (dev environment etc). PowerVC / Pow
 
 <!-- div:left-panel -->
 
-**Starting Point**: Merlin admin already created an Inventory entry with your IBM i and authorized you to use it. System name with arcad-example application: MONZA, IP Address is *will be provided to you*.
+**Starting Point**: Under **Connections**, Merlin admin already created an Inventory entry with your IBM i hostname and authorized you to use it. 
 
 <!-- div:right-panel -->
 
@@ -89,11 +87,7 @@ Merlin can provision IBM i VM for a project (dev environment etc). PowerVC / Pow
 
 <!-- div:left-panel -->
 
-Go to Credentials > Add new credential > fill in with your IBM i (MONZA) user profile
-
-* Name: `teamX-profile-monza`
-*	Username:  `teamX` (X from 1 to 12)
-* Password:  `abc123`
+Merlin admin already created a Credential entry with your IBM i userid and password.
 
 <!-- div:right-panel -->
 
@@ -107,39 +101,33 @@ Go to Credentials > Add new credential > fill in with your IBM i (MONZA) user pr
 
 <!-- div:left-panel -->
 
-### Creation of your template 
-
-Go to Templates > add new template
-
-* Name: `teamX-template-monza`
-* Inventory: ibmi
-* Credential: your credential created before
+Merlin admin already created a template which associates the defined inventory and credential together.  This Merlin template will be used by IBM i Developer so you can interact with your IBM i and services (compiler, debugger, arcad tools, etc.).
 
 <!-- div:right-panel -->
 
 ![](02/template.png)
 
 <!-- panels:end -->
 
-> [!TIP]
-> This Merlin template will be used by IBM i Developer so you can interact with your IBM i and services (compiler, debugger, arcad tools, etc.)
-
 ---
 
 <!-- panels:start -->
 
 <!-- div:left-panel -->
 
+<!--
 ### Launch IDE
 
 Go to Tools > Deployed Tools
 
 * Project: merlin-tools
 
 Right click on IBM i Developer, Launch the Application (you may have to Open the workspace if it doesn’t automatically)
+-->
 
 <!-- div:right-panel -->
 
+<!--
 ![](02/launch.png)
-
+-->
 <!-- panels:end -->
diff --git a/docs/workshop/03_ide.md b/docs/workshop/03_ide.md
@@ -1,12 +1,11 @@
-## IBM i Developer
 
-### Launch IDE
+## Launch IBM i Developer IDE
 
 <!-- panels:start -->
 
 <!-- div:left-panel -->
 
-From `Home>Overview` on the Merlin dashboard, launch the `IBM i Developer` application using the popup menu on the application
+From `Home>Overview` on the Merlin dashboard, launch the `IBM i Developer` application
 
 <!-- div:right-panel -->
 
@@ -30,7 +29,7 @@ From `Create Workspace`, create a workspace by selecting `IBM i Developer`
 
 ---
 
-### Clone git repository into workspace
+## Clone git repository into workspace
 
 <!-- panels:start -->
 
@@ -110,7 +109,7 @@ The workspace is now populated with the `arcad-example` project from the git rep
 
 ---
 
-### Connect project to IBM i
+## Connect project to IBM i
 
 <!-- panels:start -->
 
@@ -443,7 +442,7 @@ You can also push to the git repository by clicking the git status button at the
 
 <!-- div:left-panel -->
 
-### Change source code
+## Change source code
 
 - Save modification can be done automatically or manually (`File>Save` or key combination, e.g Ctrl+S (depends on preferences)).
 - After the save, a badge appears on the Git icon and a `M` to the right of the source member to indicate the file has been modified.
diff --git a/docs/workshop/06_cicd.md b/docs/workshop/06_cicd.md
@@ -6,7 +6,7 @@
 
 <!-- div:left-panel -->
 
-From `Home>Overview` on the Merlin dashboard, launch the `IBM i CI/CD` application using the popup menu on the application
+From `Home>Overview` on the Merlin dashboard, launch the `IBM i CI/CD` application
 
 <!-- div:right-panel -->
 
diff --git a/docs/workshop/ide_overview.md b/docs/workshop/ide_overview.md
@@ -1,12 +1,14 @@
 
+## IDE Workspace
+
 ![](ide_overview/overview.png)
 
 * Green panel: Explorer Panel, file explorer containing  git repository files (source) + other IBM i specific explorers like IBM i Project Explorer, Arcad view, Job Logs…
 * Orange panel: central code Panel, where you can visualize and update your source code.
 * Red panel:  outline view displays all defined variables, structs and files in active editor
 * Blue panel: Problems & Output view, compilation output, warnings, etc.
 
-### ILE RPG has most support
+## ILE RPG has extensive support
 
 * Outline
 * Model created
@@ -19,9 +21,8 @@
    * And lets you go to those calls
 * Collapsible blocks of code
 
-## Features
 
-### Tokenisation
+### Tokenization
 
 ![](ide_overview/tokens.png)
 
@@ -72,7 +73,7 @@
 
 <!-- div:left-panel -->
 
-### SQL
+## SQL
 
 * Tokenization
 * Formatting
@@ -87,6 +88,7 @@
 
 ---
 
+## IBM i Workspace actions
 <!-- panels:start -->
 
 <!-- div:left-panel -->
@@ -112,7 +114,7 @@ Press F1, then type “IBM” to see the IBM i functions available:
 
 <!-- div:left-panel -->
 
-### Fast open
+## Fast open
 
 Using Control/Command + P to filter workspace files.
 
diff --git a/docs/workshop/readme.md b/docs/workshop/readme.md
@@ -1,9 +1,9 @@
 ### Your Mission
 
-Your mission is to modernize your application and development practices, from green screen to a collaborative git/VS Code era with DevOps automation 😄
+Your mission is to modernize your application and development practices, from green screen to a collaborative git/VS Code era with DevOps automation 😄 .  The ARCAD-EXAMPLE application will be used.
 
-Merlin can support any kind of build mechanisms (like GNU make, or BoB) but as it is a complex application, decision was made to use Merlin with its powerful Arcad Software features.  ARCAD-EXAMPLE app is already initialized in Merlin/Arcad…
+Merlin can support any kind of build mechanisms (like GNU make, or BoB).  As the example application is a complex application, the decision was made to use Merlin with its powerful Arcad Software features.  The example application is already initialized in Merlin/Arcad.
 
-You are part of a team of 12 developers, on-boarded on Merlin: team1 to 12, all working on the same arcad-example application, on distinct branches feature/teamXX (XX = 1 to 12).
+You are part of a team developers on-boarded on Merlin.  Each developer will work on the same arcad-example application on distinct branches.
 
-The Application source members have already been migrated from QSYS.LIB to a git repository, managed by Merlin as an Arcad Project.  Webhooks are configured on Git so every action in git is caught by Merlin/Arcad Builder.
+The application source members have already been migrated from QSYS.LIB to a git repository, managed by Merlin as an Arcad Project.  Webhooks are configured on Git so every action in git is caught by Merlin/Arcad Builder.
