Skip to content
This repository was archived by the owner on Mar 29, 2022. It is now read-only.

Commit c1d0200

Browse files
wjallenwjallen
committed
moving around create app pages, first pass at new create app
1 parent b5c954a commit c1d0200

18 files changed

+838
-94
lines changed

‎docs/01.request_access.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Account confirmation may take up to 1-2 business days.
1818
<br>
1919
#### GitLab
2020
Depending on how you plan to interact with and use the SD2E platform, you may
21-
also need access to the [SD2E Gitlab](https://gitlab.sd2e.org/). Once your TACC
21+
also need access to the [SD2E GitLab](https://gitlab.sd2e.org/). Once your TACC
2222
account and SD2E access are confirmed, request access to Gitlab by posting in
2323
the `#cyberinfrastructure` channel of the
2424
[SD2E Team Slack](https://sd2e.slack.com/messages).

‎docs/03.apps_ci_jenkins.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Intro text.
2222
<br>
2323
#### Header 2
2424

25-
[Example link](https://url/)
25+
[Example link](https://url/)
2626

2727

2828
<br>

‎docs/03.apps_deploy.md

-34
This file was deleted.

‎docs/03.apps_init.md

-34
This file was deleted.

‎docs/03.create_app.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
layout: page
3+
title: Create a Custom Application
4+
tagline:
5+
---
6+
7+
##### *NOTE: The app building guide presented here is a work in progress, and it uses a development branch of the SD2E CLI. Please proceed with caution. If you would instead prefer to follow the old, but safe, app building guide, please go [here](old/03.old_create_app.md)*
8+
9+
10+
11+
<br><br><br>
12+
You can find Agave applications ("apps") in the SD2E catalog by using the `apps-list`
13+
command described [previously](02.find_application.md). What if the app you are
14+
looking for is not available? Using the Agave CLI, you can create your own.
15+
16+
<br>
17+
#### Components of an app
18+
19+
The essential components you need to create your own app are:
20+
21+
1. A Docker image containing the executable and all runtime dependencies
22+
2. A wrapper script (generally written in bash) that runs the executable
23+
3. A test script (also written in bash) for testing the executable outside of the Agave environment
24+
25+
Several example apps exist and all components are visible. For example, visit the
26+
[SD2E Docker Hub](https://hub.docker.com/u/sd2e/) to view existing app containers.
27+
And, example app bundles can be viewed on the
28+
[SD2E GitHub page](https://github.com/SD2E/reactors-etl/tree/master/reactors)
29+
or [SD2E GitLab](https://gitlab.sd2e.org/).
30+
31+
<br>
32+
#### Create your own by example
33+
34+
The best way to demonstrate the creation of a custom app is by example. The
35+
following sub-pages will go through the process:
36+
37+
1. [Set up your environment](03.create_app_01.md)
38+
2. [Initiate the app directory](03.create_app_02.md)
39+
3. [Containerize the executable](03.create_app_03.md)
40+
4. [Deploy and test](03.create_app_04.md)
41+
5. [Best practices and next steps](03.create_app_05.md)
42+
43+
44+
45+
46+
---
47+
Return to the [API Documentation Overview](../index.md)

‎docs/03.create_app_01.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
layout: page
3+
title: Create a Custom Application
4+
tagline: Set up your environment
5+
---
6+
7+
8+
To create and ultimately deploy Agave apps for you and others to use, GitLab and
9+
Docker Hub credentials are required. The GitLab credentials will facilitate
10+
interactions with other SD2E GitLab assets, and provide a convenient way to
11+
store your app bundle. The Docker Hub credentials are required to store an image
12+
of your executable somewhere that is accessible from multiple platforms. The
13+
SD2E CLI offers a few tools to help authenticate with and manage credentials for
14+
these resources.
15+
16+
17+
<br>
18+
#### Agave authentication
19+
20+
If you have been following along with previous sections of this user guide, you
21+
are likely already set up to interact with the SD2E Agave tenant. Use the
22+
`auth-check` command to confirm:
23+
```
24+
% auth-check
25+
tenant: sd2e
26+
username: username
27+
time left: 13179 seconds
28+
expires at: Wed Apr 25 19:38:44 CDT 2018
29+
```
30+
31+
If you are not already authenticated with the SD2E tenant, please refer to
32+
[this previous section](01.creaet_client.md) of the user guide.
33+
34+
35+
<br>
36+
#### Configure the development SD2E CLI
37+
38+
At this time, the commands to facilitate app building are not part of the master
39+
branch of the SD2E CLI. To download the appropriate development branch and put
40+
the new commands in your `PATH`, perform the following:
41+
```
42+
% wget https://github.com/SD2E/sd2e-cli/raw/ci/sd2e-cloud-cli.tgz
43+
% tar -xvzf sd2e-cloud-cli.tgz
44+
% export PATH=$PWD/sd2e-cloud-cli/bin:$PATH
45+
```
46+
47+
Check the version of the CLI that is in your `PATH` with the following:
48+
```
49+
% sd2e info
50+
51+
DARPA SD2E version: 1.1.0
52+
TACC Cloud API tenant: sd2e.org
53+
TACC Cloud API versions:
54+
Science APIs: 2.2.5
55+
Reactors API: dev
56+
TACC Accounting API: v1
57+
```
58+
59+
60+
<br>
61+
#### Authenticate with the SD2E GitLab
62+
63+
In this developmental SD2E CLI, a new `tacclab` command is present to manage
64+
authentication with the SD2E GitLab. To login, perform the following:
65+
```
66+
% tacclab login
67+
Gitlab username []: username
68+
Gitlab password:
69+
Log into TACC.cloud Gitlab:
70+
[NOTE] Gitlab token for sd2e:username stored
71+
6fa807b8a99c5e45142a83de48239814217b4f9d30379db39edd6dd3d6d0
72+
```
73+
74+
Enter the credentials you use to login to the [SD2E GitLab](https://gitlab.sd2e.org/),
75+
which are likely your TACC credentials. The command above will store a token
76+
in `~/.agave/gitlab`. Confirm the operation worked by listing the available
77+
projects:
78+
```
79+
% tacclab projects list
80+
Projects
81+
========
82+
sd2program/agave-ci-support
83+
sd2program/agave-cli
84+
sd2program/apply-recursive-pems-reactor
85+
sd2program/app_rnaseq_broad
86+
... etc.
87+
```
88+
89+
Issuing '`tacclab help`' will reveal [additional commands](06.commands_reference.html).
90+
91+
92+
<br>
93+
#### Authenticate with Docker Hub
94+
95+
Similar to the above, a new `taccreg` command was designed to manage authentication
96+
with your preferred Docker Hub. Here, you can enter your personal Docker Hub
97+
credentials, and, if you have access, the name of the main SD2E Docker Hub organization:
98+
```
99+
% taccreg login
100+
[NOTE] Log into Docker Registry:
101+
Registry username []: username
102+
Registry password []:
103+
Registry organization (optional) []:
104+
Authenticating as username...
105+
Login Succeeded
106+
```
107+
108+
In this example, the 'Registry organization' line was left blank. However, if
109+
you have been previously granted permissions, '`SD2E`' could be entered. The
110+
authentication token is stored in `~/.agave/registry`.
111+
[More usage options](06.commands_reference.html) can be found with '`taccreg help`'.
112+
113+
---
114+
Proceed to [Initiate the App Directory](03.create_app_02.md)
115+
116+
Go back to [Create Custom Applications](03.create_app.md)
117+
118+
Return to the [API Documentation Overview](../index.md)

‎docs/03.create_app_02.md

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
layout: page
3+
title: Create a Custom Application
4+
tagline: Initiate the app directory
5+
---
6+
7+
<br>
8+
#### Create an app
9+
10+
Here, we will take the first steps in developing our own Agave app. It is assumed
11+
that you already have an executable in mind (i.e. a program that you would like
12+
to run), and you have an idea of how you would like to run it (i.e. what are the
13+
inputs and outputs, what flags might be used, etc.).
14+
15+
To begin, run the `apps-init` command without any options:
16+
```
17+
% apps-init
18+
Directory maximum-osprey created.
19+
Git config for maximum-osprey initialized.
20+
... etc.
21+
```
22+
23+
The command will choose a random name and establish a template directory of the
24+
following form:
25+
```
26+
maximum-osprey/
27+
├── Dockerfile
28+
├── app.ini
29+
├── config.yml
30+
├── maximum-osprey-0.1.0
31+
│   ├── _lib
32+
│   │   ├── CONTAINER_IMAGE
33+
│   │   └── extend-runtime.sh
34+
│   ├── app.json.j2
35+
│   ├── job.json.j2
36+
│   ├── runner-template.sh
37+
│   └── tester.sh
38+
└── tests
39+
```
40+
41+
Try again, but with some flags this time:
42+
```
43+
% apps-init -n fastqc -a fastqc -r 0.11.6
44+
```
45+
```
46+
.
47+
├── Dockerfile
48+
├── app.ini
49+
├── config.yml
50+
├── fastqc-0.11.6
51+
│   ├── _lib
52+
│   │   ├── CONTAINER_IMAGE
53+
│   │   └── extend-runtime.sh
54+
│   ├── app.json.j2
55+
│   ├── job.json.j2
56+
│   ├── runner-template.sh
57+
│   └── tester.sh
58+
└── tests
59+
```
60+
61+
<br>
62+
#### Edit app.ini
63+
64+
<br>
65+
#### Edit config.yml
66+
67+
<br>
68+
#### Edit app.json.j2
69+
70+
<br>
71+
#### Edit job.json.j2
72+
73+
<br>
74+
#### Edit runner-template.sh
75+
76+
77+
78+
79+
---
80+
Proceed to [Containerize the Executable](03.create_app_03.md)
81+
82+
Go back to [Create Custom Applications](03.create_app.md)
83+
84+
Return to the [API Documentation Overview](../index.md)

0 commit comments

Comments
 (0)