diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..2a7d6c1 --- /dev/null +++ b/README.rst @@ -0,0 +1,191 @@ +=============== +Using CI/CD App +=============== + +This is a step by step guide how to use CI/CD application. + +1. Download Murano Packages/Applications +---------------------------------------- + +For users ++++++++++ + +All Applications are available in App Catalog. +The main one is: +http://apps.openstack.org/#tab=murano-apps&asset=CiCdEnvironment + +For Developers +++++++++++++++ + +For manually uploading the packages to Murano, user need to upload them +in special order, otherwise it may lead to automatic loading their dependencies +from App Catalog, which has probably the different versions of these packages. + +For development purposes special script can be used: +https://github.com/openstack/ci-cd-pipeline-app-murano/blob/master/tools/prepare_packages.sh + +The right order of manual load packages via Murano UI is +(same order is used in script mentioned above): + + - Puppet + - SystemConfig + - OpenLDAP + - Gerrit + - Jenkins + - Zuul + - NodePool + - CICDEnvironment + +2. Install CI/CD Application via Murano UI +------------------------------------------ + +For more information how to use Murano is available here: +http://murano.readthedocs.io/en/latest/draft/enduser-guide/quickstart.html + +For the CI/CD application in this repo specify the following parameters: + 1.First panel: + - Root Username + - Root Password + - Root User Email + - Username + - Password + - Email + +This is user credentials - for admin and common user. +If you have you own .gitconfig file on desktop, you can change user credentials +or use default settings. + + 2.Second panel: + - Instance flavor + - Instance image + - Key Pair + - Availability zone + - Instance Naming Pattern + +For successful deployment of murano app, user need to download special image +with pre-installed murano-agent. If you want to create your own image, then +follow the instruction: +http://docs.openstack.org/developer/murano/image_builders/linux.html + +Then deploy your application in environment. + +3. Find links on the deployed services +-------------------------------------- + +When application is finally deployed, go to **Environments** panel, choose +the newly deployed environment and open the **Latest Deployment Log** tab. +Scroll down and click on Jenkins, Gerrit URLs. + +Known issue: + +Need to add mapping hostname to your local desktop to have access to Gerrit Web +form. Also the same issue exists for Jenkins, so repeat it for Jenkins VM too. + +How to fix: + +Execute command: *sudo echo " >> /etc/hosts* on your +local desktop and on Jenkins VM (via ssh). Where: + + - is IP of Gerrit VM, which is available at + **Latest Deployment Log** tab. (it's a hyperlink like http://xx.xx.xx.xx:80) + - is a hostname displayed in web browser URL after click + on the link at **Latest Deployment Log** tab. (as above, it's + http://xx.xx.xx.xx:80). + +4. Add new project +------------------ + +- Log in to Gerrit with login/password provided via UI on step 2 (they are + also can be found at the **Latest Deployment Log** tab). Go to user’s + **Settings** -> **SSH Public Keys**. Add your public ssh key. + +- Open **Projects** -> **List**. Choose open-paas/project-config. + Clone project via SSH. For example: + *git clone ssh://@hostname:29418/open-paas/project-config* + +- Add new project to Gerrit config, like it works for Openstack Infra. + Open gerrit/projects.yaml in project-config repo from previous step and add + something like:: + + - project: demo/petclinic + description: petclinic description + upstream: https://github.com/sn00p/spring-petclinic + acl-config: /home/gerrit2/acls/open-paas/project-config.config + + Ideally ACL file should be different, but for simple example we can use + the existing one. + +- Set correct options as default from step 2 for your ~/.gitconfig on desktop + by adding the following lines:: + + [user] + email = user@mail.com + name = user + + Skip this step if you have your own ~/.gitconfig and you already specified + correct name and mail on step 2. + +- Commit changes and push to review:: + + git add . + git commit -am "Add Petclinic Project" + git review -r origin master + +- When change is uploaded to Gerrit, re-login with root user credentials. + Open proposed patch, set Code-Review +2 and click **Submit**. + +- Wait a while until your changes are being merged into the repository (it may + take from 1 to 5 minutes). Re-login with user’s credentials and open + **Projects** -> **List** again. New project should be in the project list + now. + +5. Configure and run Jenkins job for your project +------------------------------------------------- + +Known issue: +We already have template for Maven job, but it is not applied by default. + +How to fix: +To apply this job template you need to connect to Jenkins VM via ssh. Login +as **root** and execute command: +**jenkins-jobs update /etc/project-config/jenkins/jobs** + +- Go to Jenkins UI form, open created job and and configure it. Set + **Source Code management** to *Git* .Set **Repository url** as it's displayed + in Gerrit. For example: + **ssh://@:29418/demo/petclinic** + + Use **jenkins** user in link above instead of ****. + +- If you work with the demo/petclinic test project as it demostrated on + previous steps, then you need an additional configuration here: + Set **Branch** to *Spring-Security*, for current project. + In section **Build** in field **Goals and Options** write: *tomcat7:deploy* + +- Run Job and make sure that it is deployed in tomcat server. + Currently it's hardcoded inside of the mentioned repository of custom + petclinic project. For normal work you need to update **pom.xml** file to + reference on correct IP address with Tomcat server. When it's ready, open URL + with your project. For example: + **http://:8080/petclinic** + +6. Update project and re-run Jenkins job +---------------------------------------- + +- Clone petclinic project. For example: + **git clone ssh://@:29418/demo/petclinic** + +- Change branch in repo to **Spring-Security**:: + + git checkout Spring-Security + +- Change the following file in this repository: + **src/main/webapp/WEB-INF/jsp/welcome.jsp**. For example,replace word + **Welcome** with **Hi there!**. Commit and push on review:: + + git add . + git commit -am "Patch with changes" + git review -r origin Spring-Security + +- Re-login with root credentials and merge this patch. +- Re-run job in Jenkins. And re-check Tomcat server again.