small changes to apps_ci_jenkins

Author: wjallen

docs/03.apps_ci_jenkins.md

@@ -4,26 +4,26 @@ title: Continuous Integration with Jenkins
 tagline:
 ---
 
-Jenkins is an automation server for running continuous integration tests. The SD2E project uses
-[Jenkins](http://jenkins.sd2e.org/) for continuous integration (CI) to ensure
-any changes that have been made to apps do not break their
-core functionality. It is now standard practice to set up CI for all Agave apps.
-This will ensure your deployed app is always up to date with the master branch
-of your git repo, and it will alert you if jobs are not working. This guide will
-help you integrate continuous integration testing into any app you would like to
-deploy, but is not meant to be a replacement for the [Jenkins documentation](https://jenkins.io/doc/).
-
-
+Jenkins is an automation server for running continuous integration tests. The
+SD2E project uses [Jenkins](http://jenkins.sd2e.org/) for continuous integration
+(CI) to ensure any changes that have been made to apps do not break their core
+functionality. It is now standard practice to set up CI for all Agave apps. This
+will ensure your deployed app is always up to date with the master branch of
+your git repo, and it will alert you if jobs are not working. This guide will
+help you integrate CI testing into any app you would like to deploy, but is not
+meant to be a replacement for the
+[Jenkins documentation](https://jenkins.io/doc/).
 
 
 
 <br>
-#### The Jenkins File
-The Jenkins file defines the stages of your Jenkins job and defines the environment
-variables for that job. The Jenkins file is written in Groovy, and should be located
-at the top-level directory for your app. For the previous fastqc app example, the
-Jenkins file would be in the `~/fastqc-app/` directory. Here is an example of the Jenkins
-file for the fastqc app:
+#### The Jenkins file
+
+The Jenkins file defines the stages and environment variables of your Jenkins
+job. The Jenkins file is written in [Groovy](http://groovy-lang.org/), and
+should be located at the top-level directory for your app. For the previous
+FastQC app example, the Jenkins file would be in the `~/fastqc-app/` directory.
+Here is an example of a Jenkins file for the FastQC app:
 
 ```
 #!groovy
@@ -68,14 +68,12 @@ pipeline {
         stage('Run a test job') {
             steps {
                 sh "run-test-job deploy-${AGAVE_USERNAME}-job.json ${AGAVE_JOB_TIMEOUT}"
-                // Assumption here is that run_test_job generates a job.jobid file
-                // Might be smart to check if it exists if we want to bundle this step with previous in a step
                 sh "get-test-job-outputs deploy-${AGAVE_USERNAME}-job.json.jobid ${AGAVE_JOB_GET_DIR}"
             }
         }
         stage('Validate results') {
             steps {
-                sh "python -m pytest tests/validate_job --job-directory ${AGAVE_JOB_GET_DIR}"
+                sh "python -m pytest tests/validate-job --job-directory ${AGAVE_JOB_GET_DIR}"
             }
         }
     }
@@ -91,51 +89,73 @@ pipeline {
 
 ```
 
-For the most part, you won't need to change any of the environment variables in
-the groovy file. All the Jenkins jobs will run as the `sd2etest` user. You will
-need to define the input data for your app, see the `AGAVE_DATA_URI` field. If
-your test data is located in your private storage system `data-tacc-work-username`,
-you'll need to give the `sd2etest` user access to that system with the following
-CLI command:
+Copy and paste the above text into a file called `Jenkinsfile` in the top level
+of your `~/fastqc-app/` directory.
+
+The file is divided into three sections: `environment`, `stages`, and `post`.
+The `environment` section defines environment variables needed by the Jenkins
+server to run the test job. Most of the variables in this section are specific
+to the Jenkins server and should be left alone. The `CONTAINER_REPO` and
+`CONTAINER_TAG` variables should, collectively, point to a "test" repository
+location so that the versioned app is not overwritten. It is good practice to
+use the app name (e.g. "`fastqc`") as the `CONTAINER_REPO`, and "`test`" as the
+`CONTAINER_TAG`.
+
+You may also need to change `AGAVE_DATA_URI` if your data is located on some
+other system or in a different path. Also note that if your test data is located
+in your private storage system, `data-tacc-work-username`, you will need to grant
+`READ` access to the `sd2etest` user with the following command:
+
 ```
 systems-roles-addupdate -u sd2etest -r USER data-tacc-work-username
 ```
 
-The stages of a Jenkins test will also remain largely unchanged. You will always
-need to
+The `stages` section of the Jenkins file will also remain largely unchanged. You
+will typically need the following sections:
 1. `Create Oauth client`
 2. `Build container`
 3. `Deploy to TACC.cloud`
 4. `Run a test job`, and
 5. `Validate results`
 
-To validate your results, you'll need to define pytests that will be run to verify your app is functional.
-For the fastqc app, navigate to the tests directory `~/fastqc-app/tests`, and create
-a new directory called "validate_job":
+The first four steps depend on scripts that exist on the Jenkins server, and
+should work the same for most apps. The final step must be written by the app
+developer, and will be different from app to app. More details on this step are
+included in the next section below.
+
+Finally, the `post` section uses one more script on the Jenkins server to clean
+up the session and exit the Jenkins test. This section should not change.
+
+<br>
+#### Validating results with pytests
+
+To validate your results, you will need to define pytests that will be run to
+verify your app is functional. For the FastQC app, navigate to the tests
+directory `~/fastqc-app/tests`, and create a new sub-directory called
+`validate-job`:
 ```
 cd ~/fastqc-app/tests
-mkdir validate_job
-cd validate_job
+mkdir validate-job
+cd validate-job
 ```
 
-Create two pytests in that directory, `conftest.py` and `test_files.py`. You can copy/paste
-these two examples,
-conftest.py:
+Create two pytests in that directory, `conftest.py` and `test_files.py`. You can
+copy and paste these two examples directly:
+
+`conftest.py`:
 ```
 import pytest
 
-
 def pytest_addoption(parser):
     parser.addoption("--job-directory", action="store", default="job_output",
                      help="Directory containing output to evaluate")
 
-
 @pytest.fixture
 def job_directory(request):
     return request.config.getoption("--job-directory")
 ```
 
-test_files.py:
+`test_files.py`:
 ```
 '''Test for specific files existence in a directory'''
 import pytest
@@ -160,9 +180,9 @@ def test_files(job_directory,file_list):
             raise IOError("Couldn't stat {}".format(f))
 ```
 
-The conftest.py adds a --job-directory option to pytest, this points to the location of
-the output files that are created by running your app. The pytest test_files.py checks if
-files exist and are greater than 0 bytes.
+The `conftest.py` adds a `--job-directory` option to pytest, this points to the
+location of the output files that are created by running your app. The pytest
+`test_files.py` checks if files exist and are greater than 0 bytes.
 
 If you are creating pytests for a different app, you can simply change the output
 file names in line 7 of `test_files.py`, to the file names that are output by your app:
@@ -173,21 +193,22 @@ file names in line 7 of `test_files.py`, to the file names that are output by yo
     (['reads1_fastqc.html', 'reads1_fastqc.zip'])
 ])
 ```
-In this example, Jenkins is testing for the existence of reads1_fastqc.html and
-reads1_fastqc.zip, which indicate that the fastqc app ran successfully.
+In this example, Jenkins is testing for the existence of `reads1_fastqc.html`
+and `reads1_fastqc.zip`, which indicate that the FastQC app ran successfully.
 
 <br>
-#### Setting up the Jenkins Server
-Now that you've created a groovy file and defined pytests,
-you'll need to add your repo to the Jenkins server and define when it should
-run tests. We typically have the server run a test every time a changed is pushed
-to the master branch, or anytime a merge request to the master branch is made. It
-may also be a good idea to schedule weekly or monthly builds to ensure you app
+#### Setting up the Jenkins server
+
+Now that you have created a groovy file and defined pytests, you will need to
+add your repo to the Jenkins server and define when it should run tests. We
+typically have the server run a test every time a changed is pushed to the
+master branch, or anytime a merge request to the master branch is made. It may
+also be a good idea to schedule weekly or monthly builds to ensure your app
 continues working even when no changes have been made to the source repo.
 
 To set up Jenkins tests for your app, follow the instructions in this video tutorial:
-<iframe width="560" height="315" src="https://www.youtube.com/embed/XfhgGZ0CAPw" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
 
+<iframe width="560" height="315" src="https://www.youtube.com/embed/XfhgGZ0CAPw" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
 
 
 ---

index.md

@@ -51,7 +51,7 @@ the SD2E platform. Documentation for getting started with the SD2E API is below.
 
     3.3 [Modify an Existing Application](docs/03.modify_app.md)
 
-    3.4 [Continuous Integration with Jenkins](docs/03.apps_ci_jenkins.md) (*work in progress*)
+    3.4 [Continuous Integration with Jenkins](docs/03.apps_ci_jenkins.md)
 
     3.5 [Old App Building Process](docs/old/03.old_create_app.md) (*deprecated*)