Merge pull request #35 from IBM/add-docs4merlin

Merlin User guide and Administrator guide

Author: eric-simpson

README.md

@@ -1,8 +1,8 @@
 # Merlin Docs
 
-Hands-On Documentation for IBM i Merlin repository.
+Documentation for IBM i Merlin repository.
 
 ## What is this for?
 
-* This hands-on documentation is not meant to replace the official [IBM Documentation for Merlin](https://www.ibm.com/docs/en/merlin/1.0?topic=overview).
-* These guides are for users getting started with Merlin step-by-step.
+* This documentation includes hands-on tutorials, user guide, and administrator guide.
+* Version 1.0 documentation is at [IBM Documentation for Merlin](https://www.ibm.com/docs/en/merlin/1.0?topic=overview).

docs/README.md

@@ -1,19 +1,20 @@
 ![](./images/overview/main.png)
 
-Welcome to the hands-on documentation for IBM i Merlin. This hands-on documentation is not meant to replace the official [IBM Documentation for Merlin](https://www.ibm.com/docs/en/merlin/1.0?topic=overview).
+Welcome to the documentation for IBM i Merlin. This includes hands-on tutorials, user guide, and administrator guide.
 
 IBM i Modernization Engine for Lifecycle Integration (Merlin) is a set of tools run in OpenShift containers which guide and assist software developers in the modernization of IBM i applications, allowing them to realize the value of a hybrid cloud, multi-platform DevOps implementation.  
 
 **News**: Version 2.0 has been [announced](https://www.ibm.com/docs/en/announcements/i-modernization-engine-lifecycle-integration-merlin-20) and will be available June 14, 2024!  
 
+Version 1.0 documentation is available at [IBM Documentation for Merlin](https://www.ibm.com/docs/en/merlin/1.0?topic=overview).
+
 #### Getting started videos
 
 * **for users**: [YouTube video playlist](https://www.youtube.com/playlist?list=PLPELYviDwCnY6L5r5ZnmCneqhakLcB7ko). Starts with set of videos for configuring the web browser, just watch the video corresponding to your system then continue with the rest.
 * **for administrators**: [YouTube video playlist](https://www.youtube.com/watch?v=6UlN1vhrCPo&list=PLPELYviDwCnajC310KB2K7zfu51FPuYJS).
 
 #### Getting help
 
-* See the [product documentation site](https://www.ibm.com/docs/en/merlin/1.0?topic=overview) for more information.
 * Submit product requests using the [IBM Power Systems Ideas Portal](https://ibm-power-systems.ideas.ibm.com/?category=7112512098562980476).
 * Discuss the product with other users on the [IBM Community](https://community.ibm.com/community/user/power/communities/community-home?communitykey=f0246bc4-08f3-43c5-a7f8-b6a64d387894).
 * For support, open a case on the [Support portal](https://www.ibm.com/mysupport/).  Also, subscribe to [product notifications](https://www.ibm.com/systems/support/myview/subscription/css.wss).
@@ -22,7 +23,7 @@ IBM i Modernization Engine for Lifecycle Integration (Merlin) is a set of tools
 #### Additional resources
 
 * Check out the official [Security considerations](https://www.ibm.com/docs/en/merlin/1.0?topic=overview-security-considerations) from IBM.
-* See the [announcement](https://www.ibm.com/common/ssi/ShowDoc.wss?docURL=/common/ssi/rep_ca/8/897/ENUS222-128/index.html) for ordering details.
+* See the [Version 1 announcement](https://www.ibm.com/common/ssi/ShowDoc.wss?docURL=/common/ssi/rep_ca/8/897/ENUS222-128/index.html).
 * See the [product page](https://www.ibm.com/products/ibm-i-merlin) for more information.
 * See [Frequently Asked Questions](https://www.ibm.com/support/pages/ibm-i-modernization-engine-lifecycle-integration-merlin-overview#faq).
 * Visit [YouTube](https://www.youtube.com/playlist?list=PLPELYviDwCnYe60cNHs_Hf-4Sr8h_0uVE) for a play list of videos to learn more about Merlin including the integration with ARCAD tools.

docs/guides/appinstall.md

@@ -68,4 +68,4 @@ Clicking Finish takes you back to the 'Deployed Tools' page where you can see th
 
 ![](../images/appinst/appinst-8.png)
 
-When it is finished installing, you can right-click and select 'Launch Application'. This takes you into CodeReady Workspaces.
+When it is finished installing, you can right-click and select 'Launch Application'. This takes you into developer workspaces.

docs/guides/cicd/Configure_Log_Level.md

@@ -0,0 +1,6 @@
+# Configure log level
+IBM i CI/CD GUI supports configuring the log level. The default log level is INFO, but that sets it to a different level is supported.
+The log levels supported for GUI are **OFF**, **SEVERE**, **WARNING**, **INFO**, **FINEST**, **ALL**.  
+
+![CICD_Configure_Log_Level](../../images/guides/CICD_Configure_Log_Level.png)
+

docs/guides/cicd/Deploy_and_initialize_IBM_i_CICD.md

@@ -0,0 +1,66 @@
+# Deploy and Initialize IBM i CI/CD
+
+## Deploy IBM i CI/CD from Merlin platform
+
+* Install IBM i CI/CD in the **Catalog** from Merlin platform 
+
+    * Follow the **Installation Application** wizard to complete the installation of IBM i CI/CD.
+       ![IBM i CI/CD Installation Wizard](../../images/guides/cicdCatalog.png)
+
+* Launch IBM i CI/CD from Merlin platform
+
+    *  Under **Overview > Quick Launch**, click to launch **IBM i CI/CD** directly.
+    *  Under **Tools > Deployed Tools**, right click and launch **IBM i CI/CD** in context menu.
+
+## Initialize Jenkins in IBM i CI/CD GUI
+Jenkins is the automation server behind IBM i CI/CD which runs the actual build and deploy jobs. Both internal Jenkins and external Jenkins are supported in IBM i CI/CD, internal Jenkins comes with IBM i CI/CD and external Jenkins can be existing Jenkins.
+
+Both internal and external Jenkins must be initialized before using in IBM i CI/CD. While the initialization of external Jenkins only saves the information (Jenkins URL, username, password, and API token) for authentication with Jenkins REST API into Merlin platform, the initialization of internal Jenkins will do the actual configuration of Jenkins. 
+
+Use **Jenkins Configuration > Jenkins Server > Initialize Jenkins** to open the **Initialize Jenkins** wizard.   
+**Note**: **Initialize Jenkins** requires an admin user role.
+* Initialize internal Jenkins 
+    * Select **Use internal Jenkins server** in step **Select Jenkins server type**.
+    ![Use Internal Jenkins Server](../../images/guides/cicdSelectInternalJenkins.png)
+
+    * Input Jenkins username and password in step **Initialize default Jenkins server**.
+    The user will be created in internal Jenkins and used for later authentication with Jenkins.
+    ![Initialize Jenkins Using Default Wizard](../../images/guides/cicdInitializeJenkinsUsingDefaultWizard.png)
+
+    * Wait for the initialization of internal Jenkins to finish. Jenkins server information will be refreshed and the **Connectivity** will be **Available** if the initialization is finished successfully. 
+    ![Initialize Internal Jenkins Success](../../images/guides/cicdInitializeInternalJenkinsSuccess.png)
+
+* Initialize external Jenkins
+    * Select **Use external Jenkins server** in step **Select Jenkins server type**.
+    ![Use Internal Jenkins Server](../../images/guides/cicdSelectExternalJenkins.png)
+
+    * Input external Jenkins server information in step **Specify Jenkins server information**.
+        ![Specify Jenkins Server Information](../../images/guides/cicdSpecifyJenkinsServerInformation.png)
+        * **Note:** Use the **Generate API token** button to get the **API token** after filling in the Jenkins server URL, username, and password. The API token is required when authentication with Jenkins server REST API. 
+        * **Note:** Use the **Test TLS** button to verify if the TLS is configured on the external Jenkins server and import the CA certificate into the trust store if it is not.
+    * Wait for the initialization of external Jenkins to finish. Jenkins information will be refreshed and the **Connectivity** will be **Available** if the initialization process is finished successfully. 
+* **Note**: Another option to set external Jenkins is using the **Edit selected Jenkins server** button. Add an available Jenkins template in Merlin platform first and select the added Jenkins template. Use the **Test TLS** button to verify if the TLS is configured on the selected Jenkins server and import the CA certificate into the trust store if it is not.
+![Edit selected Jenkins server](../../images/guides/cicdSetJenkinsServer.png)
+
+
+
+## Integrate ARCAD in IBM i CI/CD GUI
+
+Integrate ARCAD will enable the capability to communicate with ARCAD builder server by installing three ARCAD plugins in Jenkins, including ARCAD-Commons Plugin, ARCAD-Builder Plugin, and ARCAD-Macro Execution Plugin.
+
+Use **Jenkins Configuration > ARCAD Integration > Enable ARCAD Integration** to open the **Enable ARCAD Integration** dialog.   
+
+**Note**: **Enable ARCAD Integration** requires an admin user and only supports internal Jenkins. The integration process will overwrite all the configuration of ARCAD-Builder Plugin and ARCAD-Macro Execution in internal Jenkins. 
+
+**Note:** Currently IBM i CI/CD only supports the configuration of ARCAD builder server. The configuration of ARCAD Servers for ARCAD-Macro Execution Plugin is not supported yet while the ARCAD-Skipper CLI will be put under default location ```/merlin/cicd/gui/skipperCLI```. If the user wants to utilize the functionality of ARCAD-Macro Execution Plugin, use it in Jenkins GUI directly.
+
+* Enable ARCAD integration
+
+    * Input the ARCAD builder URL, and use **Test TLS** to verify if the TLS is configured on the  ARCAD builder server and import the CA certificate into the trust store if it is not.
+
+    * Select ARCAD builder server credential in Jenkins credential list, add the credential first under **Jenkins Configuration > Manage Jenkins Credential**.
+
+    * Wait for the ARCAR integration process to finish. And the ARCAD builder URL and selected credential name will be listed on ARCAD Integration page.
+    * Use **Test Connection** to test the connectivity of ARCAD builder server.
+    ![ARCAD Integration ](../../images/guides/cicdArcadIntegration.png)
+    

docs/guides/cicd/Manage_Logs.md

@@ -0,0 +1,3 @@
+IBM i CI/CD supports configuring log levels and viewing GUI logs.
+* [Configure Log Level](Configure_Log_Level.md)
+* [View Logs](View_Logs.md) 

docs/guides/cicd/View_Logs.md

@@ -0,0 +1,7 @@
+# View logs
+IBM i CI/CD GUI supports viewing and downloading GUI logs.
+* View or download GUI logs  
+Double-click the log file or click the View button to open the log file.  
+Click the **Download** button to download the log file to the local file system.
+
+![CICDViewGUILog](../../images/guides/CICDViewGuiLogs.png)

docs/guides/cicd/Work_with_IBM_i_CICD_profiles.md

@@ -0,0 +1,67 @@
+# Work with IBM i CI/CD tasks
+
+
+## Create IBM i CI/CD task
+IBM i CI/CD task defines the whole process of source code management, build and deploy actions. Currently IBM i CI/CD supports both private and public tasks. A private task is visible only to the user who created it while a public task is visible to all users.
+
+Use **Task Management > Create New Task** to open the **Create New Task** wizard. 
+
+* Specify General Information   
+    * Specify the task name and the type of task, private or public.
+    * Upload customized icon for the task if needed, only JPG and PNG supported.
+    ![Specify General Information](../../images/guides/cicdSpecifyGeneralInfo.png)
+* Source Code Management
+    * Define Git repositories by specifying the Git Repository URL and branch information.   
+     ![Source Code Management](../../images/guides/cicdSourceCodeMgmt.png)
+    
+        * **Note:** If multiple Git repositories are added, fill in the **Check out to subdirectory** to create a subdirectory for different repositories.
+        * **Note:** Specify credential from Jenkins credential list if current Git repository is not public.
+* Build
+    * Add build servers
+        * Specify build servers by **Add Build Server**, use customized build server name if needed. If **Specify build server (template)** is checked, select an existing server from the server list( IBM i templates defined in Merlin platform ). 
+        * If you want to upload the source code defined in step **Source Code Management**, check the checkbox **Upload source code to build server** and fill in the **Work directory** on the remote server. Source code will be uploaded automatically to the defined **Work directory** when the task runs.
+        ![Add build servers](../../images/guides/cicdAddBuildServer.png)
+
+    * Send files to server
+        * Send files to a remote server. Use the relative path of files. Use enter to separate multiple files. File directory is not supported.
+        ![Send files to server](../../images/guides/cicdSendFilesToServer.png)
+    
+    * Run CL command
+        * Run CL command in a remote server. Use enter to separate multiple CL commands.
+         ![Run CL command](../../images/guides/cicdRunCLcmd.png)
+    * Run an ARCAD-Builder build
+        * Run an ARCAD-Builder build by the ARCAD Jenkins plugins. Enable ARCAD integration first and make sure the connectivity to ARCAD build server is available.
+        ![Run an ARCAD-Builder build](../../images/guides/cicdRunArcadBuilder.png)
+        
+* Deploy   
+    * Add Deploy Server   
+        * Specify deploy servers by **Add Deploy Server**, use customized deploy server name if needed.
+         ![Add Deploy Server](../../images/guides/cicdAddDeployServer.png)
+       
+    * Send files to server
+        * The same as in Build.
+    * Run CL command
+        * The same as in Build.
+    * Distribution on IBM i 
+        *  Distribution on IBM i support transferring objects from the source library on source IBM i to the destination library on destination IBM i. 
+            * **Note:** Use **Comma** to separate multiple objects.
+        * Define multiple deployments for multiple library transfer actions. Make sure the source library and destination library exist.
+        * Support package certain objects or package the whole library at once.
+        ![Distribution on IBM i](../../images/guides/cicdDistributionOnIBMi.png)
+        
+    * Transfer files between IBM i 
+        * Transfer multiple single files between two IBM i. Use enter to separate multiple files. File directory is not supported.
+         ![Transfer files between IBM i](../../images/guides/cicdTransferFilesBetweenIBMi.png)
+       
+
+* Summary
+    * Summary of the defined Git repositories, build and deploy action in the task.
+    ![Summary](../../images/guides/cicdSummary.png)
+
+        
+
+## Run IBM i CI/CD task
+
+Right-click on the selected task and click **Run Task** to open the **Run Task** wizard. Fill in the necessary information before running the task.
+
+Every time a task runs, a new pipeline job will be created in the Jenkins server named as ```{task name}-{username}-{current time}```. While Jenkins supports building any job multiple times, IBM i CI/CD doesn't support that now.

docs/guides/cicd/Work_with_Jenkins.md

@@ -0,0 +1,56 @@
+# Work with Jenkins
+Jenkins is the automation server behind IBM i CI/CD which runs the actual build jobs. 
+
+## Jenkins Plugins
+During the initialization of the internal Jenkins server, a list of Jenkins plugins has been installed automatically in the internal Jenkins server. IBM i CI/CD GUI keeps a list of plugins with expected versions and supports the installation of missing plugins and the update of old plugins. 
+
+![Jenkins_Plugin](../../images/guides/Jenkins_Plugin.png)
+The **Missing plugins** table lists plugins that should be installed but are missing in the internal Jenkins server.  
+
+The **Plugins needs updates** table lists plugins that need updates in the internal Jenkins server.
+
+Use the **Refresh** button to refresh the Jenkins plugin installation status in the internal Jenkins server.
+
+Use the **Install / Update Jenkins Plugin** button to install the missing plugins or update the plugins which need updates.
+
+**Note:** Jenkins plugins relative functions require an admin user role and only support the internal Jenkins server.  
+**Note:** When using **Install / Update Jenkins Plugin** to install or update plugins, all the Jenkins plugins will be installed or updated to the expected version defined in IBM i CI/CD. The Jenkins server will be restarted automatically to activate the newly installed or updated plugins.  
+
+
+
+
+## Manage Jenkins credential
+IBM i CI/CD supports the management of Jenkins credentials, including add, edit and delete actions.
+* **Note:** All IBM i CI/CD users are under the same Jenkins user, and Jenkins credentials are visible to all users.
+* Add Jenkins credential
+    * Add Jenkins credential with type **Username with password**
+    ![Add Jenkins Credential Username with Password](../../images/guides/cicdJenkinsCredentialUsernamePassword.png)
+     * Add Jenkins credential with type **SSH Username with private key**
+    ![Add Jenkins Credential SSh Username with Password](../../images/guides/cicdJenkinsCredentialSSH.png)
+* Edit Jenkins Credential
+    * Edit Jenkins credential with type **Username with password**
+    ![Edit Jenkins Credential Username with Password](../../images/guides/cicdEditJenkinsCredentialUsernamePassword.png)
+     * Edit Jenkins credential with type **SSH Username with private key**
+    ![Edit Jenkins Credential SSh Username with Password](../../images/guides/cicdEditJenkinsCredentialSSH.png)
+
+## Manage Jenkins jobs
+IBM i CI/CD supports the management of Jenkins job, including refreshing job list regarding task name, stopping job build, viewing build results, and deleting Jenkins job.
+![Manage Jenkins Jobs](../../images/guides/cicdManageJenkinsJobs.png)
+* **Note:** Jenkins job supports build multiple times, but not supported for the task in IBM i CI/CD now. In case the user uses Jenkins directly, the latest build is used by IBM i CI/CD when stop build or view build results.
+
+## Manage Permission
+
+Currently, only admin users are allowed to initialize the Jenkins server for both internal and external Jenkins. If other users want to use the same Jenkins initialized by admin, the admin user can assign the permission to users by **Jenkins Configuration > Manage Permission**.
+* Manage Permission   
+The Jenkins Permission table lists users able to use the current Jenkins server. The template is created when adding Jenkins permission with the Jenkins server URL, Jenkins username, password, and API token generated for every user. 
+![Manage Jenkins Jobs](../../images/guides/cicdManageJenkinsAccessibility.png)
+
+* Assign Permission to User
+Assign permission of current Jenkins to other users. This process will automatically create connection resources with the default name ```jenkins-{cicd namespace}-username``` :
+    * Jenkins inventory with the Jenkins URL
+    * Jenkins credential with the Jenkins username, password, and automatically generated API token for every user
+    * Jenkins template with the above Jenkins inventory and credential.
+
+    ![Manage Jenkins Jobs](../../images/guides/cicdAssignJenkinsAccess.png)
+
+* **Note:** Permission table only lists users whose access to Jenkins is assigned through IBM i CI/CD, since extra data is added when using **Assign Permission to User**.

docs/guides/cicd/bob.md

@@ -0,0 +1,11 @@
+# IBM i Modernization Engine for Lifecycle Integration - DevOps CI/CD
+IBM i CI/CD aims to simplify the experience of DevOps for IBM i application development.  This provides browser-based tooling to set up and manage an automated build, test, and deployment pipeline for native IBM i applications leveraging Jenkins.
+Core capabilities provided:
+- Out-of-box Jenkins with ARCAD integration. 
+- Users can create their own Jenkins environment with capability to build and deploy IBM i programs.
+- Graphic interface to simplify key operations of Jenkins. This GUI creates Jenkins pipelines specifically for IBM i programs development.
+
+
+![Merlin CICD](../../images/guides/merlincicd.png)
+
+For information on using ARCAD tools, see [How to use ARCAD integration with IBM i Modernization Engine for Lifecycle Integration](https://supportcontent.ibm.com/support/pages/how-use-arcad-integration-ibm-i-modernization-engine-lifecycle-integration-merlin)