03.create_app_02.md

layout	title	tagline
page	Create a Custom Application	Initiate the app directory

At the core of an Agave app is an executable. It is assumed that you already have an executable in mind for your first app. It could be anything from a simple python script to a software package downloaded from the web. It is also assumed you have an idea of how you intend to run the executable, i.e. what are the inputs and outputs, what flags might be used, etc. In the example below, we will create an app using the publicly-available FastQC tool.

#### Explore a dummy app directory

To begin, try running the apps-init command without any options:

% apps-init
Directory healthy-pheasant created.
Git config for healthy-pheasant initialized.
... etc.

The command will choose a random name and set up a template directory of the following form:

healthy-pheasant/
├── Dockerfile
├── app.ini
├── config.yml
├── healthy-pheasant-0.1.0
│   ├── _lib
│   │   ├── CONTAINER_IMAGE
│   │   └── extend-runtime.sh
│   ├── app.json.j2
│   ├── job.json.j2
│   ├── runner-template.sh
│   └── tester.sh
└── tests

Several files and folders are created. It is a good idea to take some time now to look through the directory tree and examine the contents of each file. We will go through each of the files in subsequent sections.

#### Initiate the app directory

Use the apps-init command again, but this time add a few flags to indicate the name of the app you intend to build (feel free to remove the previous directory, as it was only a test):

% apps-init -n fastqc-app -a fastqc -r 0.11.7

The -n argument indicates the project name, the -a argument indicates the name of the app, and the -r argument indicates the software version. The contents of the new app directory appear as:

fastqc-app/
├── Dockerfile
├── app.ini
├── config.yml
├── fastqc-0.11.7
│   ├── _lib
│   │   ├── CONTAINER_IMAGE
│   │   └── extend-runtime.sh
│   ├── app.json.j2
│   ├── job.json.j2
│   ├── runner-template.sh
│   └── tester.sh
└── tests

Tip: more command line options can be found by issuing 'apps-init -h'

From here on, we will refer to the location of this app bundle as '~/fastqc-app/'.

#### `~/fastqc-app/app.ini`

The first file to examine is called app.ini, which contains initialization parameters for the app. By default, the fields are populated by the apps-init flags specified on the command line:

[app]
name = fastqc
version = 0.11.7
bundle = fastqc-0.11.7

[docker]
username = username
repo = fastqc
tag = 0.11.7
dockerfile = Dockerfile
buildopts =

[job]
test_data_dir =

This is your opportunity to edit the file and change the name of the app or the Docker Hub target. Make sure the username in the [docker] section matches your Docker Hub username. In this example, we will keep the defaults.

#### `~/fastqc-app/config.yml`

This file holds variables that you want to inject into the environment of your app container at run time. We have nothing to add at this time:

---
logs:
  level: DEBUG
  token: ~

Acceptable log levels are DEBUG, INFO, WARN, ERROR, FATAL.

#### `~/fastqc-app/fastqc-0.11.7/app.json.j2`

This is a templated app json file. By default, it will assign an app name, version, executionSystem, deploymentPath, and other parameters. Now is a good time to modify this file if a typical job run against this app would require, e.g., more than one node or a non standard queue. The jinja2 formatted fields surrounded by double curly braces '{{ }}' are take from app.ini.

Specific to FastQC, one input is required - a fastq file. Modify app.json.j2 to expect one input fastq file as shown below: {% raw %}

{
  "name": "{{ agave.username }}-{{ app.name }}",
  "version": "{{ app.version }}",
  "executionType": "HPC",
  "executionSystem": "hpc-tacc-wrangler-{{ agave.username }}",
  "parallelism": "SERIAL",
  "deploymentPath": "{{ agave.username }}/apps/{{ app.bundle }}",
  "deploymentSystem": "data-sd2e-projects-users",
  "defaultProcessorsPerNode": 1,
  "defaultNodeCount": 1,
  "defaultQueue": "normal",
  "label": "{{ date_time.iso8601_micro }}",
  "modules": ["load tacc-singularity"],
  "shortDescription": "{{ app.description }}",
  "templatePath": "runner-template.sh",
  "testPath": "tester.sh",
  "inputs":[
    {
      "id": "fastq",
      "value": {
        "default": "agave://data-sd2e-community/sample/sailfish/test/read1.fastq",
        "visible": true,
        "required": true
      },
      "semantics": {
        "ontology": [
          "http://edamontology.org/format_1930"
        ]
      },
      "details": {
        "label": "FASTQ sequence file"
      }
    }
  ],
  "parameters": [{
    "id": "CONTAINER_IMAGE",
    "value": {
      "default": "{{ docker.organization }}/{{ docker.repo }}:{{ docker.tag }}",
      "description": "Container Image. Do not edit.",
      "type": "string",
      "visible": false,
      "required": true
    }
  }],
  "outputs": []
}

{% endraw %}

Please refer back to the previous Agave apps documentation for a detailed breakdown of a typical app json file.

#### `~/fastqc-app/fastqc-0.11.7/job.json.j2`

The job.json.j2 file is currently blank, but will automatically be populated when the app is deployed

#### Next steps

If you have been following along, these files are ready to deploy for your app:

fastqc-app/
├── Dockerfile
├── app.ini                     # Done
├── config.yml                  # Done
├── fastqc-0.11.7
│   ├── _lib
│   │   ├── CONTAINER_IMAGE     # Do not modify
│   │   └── extend-runtime.sh   # Do not modify
│   ├── app.json.j2             # Done
│   ├── job.json.j2             # Done
│   ├── runner-template.sh
│   └── tester.sh
└── tests

Next, we will build the Dockerfile and runner_template.sh.

---

Proceed to Containerize the Executable

Go back to Create Custom Applications

Return to the API Documentation Overview