Page History
| Info | ||
|---|---|---|
| ||
There are two different ways to create custom application that may be used within EPISODES Application WorkbenchPlatform. The first one option is to use the Platform's dedicated wizard which suggests required elements and parameters used to fill in the created application. The other way second option (recommended only for advanced users) is to create a Git repository using Gitea only the Application Workbench and then create and add required (appDefinition) and optional (e.g. appDescription) files with Git. |
files by hand. |
Contents of this guide
With this guide you will learn how to create your own application that could be later used within the EPISODES Platform. Depending on your choice, you can create the application using automated tools provided by the Platform (recommended) or you can create it manually, by first, creating a repository and then adding the required files. This guide will also tell you how to check whether the application was created correctly. To learn how to edit the application files after it is created, please check this guide.
| Anchor | ||||
|---|---|---|---|---|
|
To create a new application using The dedicated wizard in the Episodes platform go to My Apps and click the Create new application button.
offered by the EPISODES Platform will allow you to create a new application using
dedicated wizard click the buttons marked above.some pre-set values and to generate all the files required for connecting an application to the EPISODES Platform in a correct form - the descriptor files will be generated using the values you choose, along with a stub of the application code matching the descriptor. Note, that we recommend using the wizard even if you already have a good knowledge of GIT and Application Workbench, as, in this way, we can ensure the application's repository contains all required files and that they are correct in relation to one another. The manual repository creation is recommended only in case you already have your code in a local GIT repository and want to connect it to the Application Workbench (and, ultimately, to EPISODES Platform).
To create a new application using the wizard, log in to the EPISODES Platform and go to My Apps tab (note, that it will not be visible before logging in to your account). Once there, use the Create New Application button (Figure 1) to open the wizard (Figure 3).
Figure 1. User apps tab in EPISODES Platform with Create new application button marked
Note, that if you do not see the Create new application button, and instead of the blue information panel, you have a red or yellow error message as shown on Figure 2, your Application Workbench account is not configured correctly. Use the Creating Application Workbench account, to check if you completed all required actions.
Figure 2. Messages displayed when the Application Workbench account is not properly configured
Once you choose to create a new application, a configuration page will be displayed (Figure 3). The panel on the left (marked with (1) in Figure 3) contains forms for filling the fields that will be used to construct the Application Description file and the stub of the main execution script compatible with it. A brief description of each field can be found when hovering over the information (i) icon next to it, and a detailed description can be found in the Application Description file guide. For the multiple input fields, the Add buttons and trash icons next to them are used to add or, respectively, remove values (see also a filled form in Figure 4). The Add application description box (marked with (2) in Figure 3) toggles displaying a form for specifying the Application Description (see Figure 5). After all the values are filled, use the Create button (within controls marked with (3) in Figure 3) to trigger the creation of application. If the process is successful, you will come back to the initial User apps view (Figure 1), but the the new application should be visible on the list of applications under the name you specified as Application repository name. See also this section to see how to check if the application was created correctly. Note, that one of the reasons of failure when creating the application could be using a name of an application that already exists as the Application repository name. The name of the new application has to be unique among your all applications.
Figure 3. View of the new application wizard, with most important elements marked
Figure 4. Left: application definition form filled with values; Right: a sample dialog window used for collecting application input information
Figure 5. Application description form filled with values
In case of any uncertainty as to the meaning of any of the form fields, please consult the Application Description file guide and Application Description file guide.
| Anchor | ||||
|---|---|---|---|---|
|
When creating the new application manually, you will first have to create the repository for the application code (using one of the options specified in the subsequent subsections), and then, configure it, so that it could be recognized by the EPISODES Platform - i.e. you will have to adjust the repository contents as specified in Custom application configuration guide. To add new files or edit the existing ones, please use the Editing the application code guide.
The repository has to be created from the Application Workbench, after logging in to it (check this guide if you do not have an account yet or have any trouble logging in). To do this, use either the menu in top right corner and the New Repository option or the + icon next to the Repositories list (both options marked in Figure 6).
Figure 6. Main view of the Application Workbench with controls that can be used for creating a new repository marked
Using any of the new repository creation options, will result in displaying a page as shown in Figure 7. The most important elements to fill here are (also marked with numbers 1-3 in Figure 7):
- Repository Name (required) - the name of the repository, that will also be used as the application name. It has to be unique among your all repositories (whether created with the EPISODES Platform wizard or manually) and may contain only alphanumeric, dash, underscore and dot characters.
- Visibility - it is strongly recommended to mark the repository as private (check the box Make Repository Private). Otherwise, the repository, and thus, the application will be visible to everyone and appear on the applications list for every user. Note, that even for the private repositories, it is still possible to share the code with other (selected) users.
- Description - short description what the repository is containing.
- Initialize Repository - if this field is checked, the repository will be already initialized and some initial files will be added (a
README.mdfile and a license, if you chose it) to it upon creation. This initialization will allow you to start working with the repository right away, otherwise, you will have to initialize it from your computer (see Figure 9). Do not check this field if you already have a local GIT repository and only want to publish it to the Application Workbench.
Other fields may be left empty, but if you already have an experience with systems based on GIT, such as Github or Gitea, configure the repository here to your convenience.
After filling the values use the Create Repository button (marked with (4) in Figure 7) to proceed with creating the repository.
Figure 7. View of the new application's repository creation with most important elements marked
If you checked the Initialize Repository (marked with (3) in Figure 7), upon choosing the Create Repository you will be taken to the main directory view of the new repository (Figure 8). At this point, you will be able to start Editing the application code to configure the application correctly.
Figure 8. Main view of the new repository
If you did not check the box next to Initialize Repository (marked with (3) in Figure 7), you will be now presented with an information page on how to initialize the repository on your own (Figure 9). This option should especially be used, when you already have a local GIT repository with your application code, but may also be followed in other cases.
Figure 9. Information page containing instructions for initializing the created repository
Anchor GitInit GitInit
Using an existing local repository
| GitInit | |
| GitInit |
If you already have your application files in an initialized GIT repository, you have to create the remote repository in Application Workbench following the previous instructions, but remembering to leave the field Initialize Repository (marked with (3) in Figure 7) unchecked. Once the repository is created, follow the instructions displayed on the information page under Pushing an existing repository from the command line (see Figure 9) - i.e. invoke the following commands:
| Code Block | ||
|---|---|---|
| ||
git remote add origin <repository_url>
git push -u origin master |
Note, that for this mode of initializing the repository, you will have to have the GIT client installed on your computer (see also this guide).
Migrating from an existing code repository
The Application Workbench allows you also to copy an existing repository you have on a different GIT server. To do this, use the link Migrate repository on the new repository creation page (Figure 7, the link is marked with (5)) or follow the direct link: https://epos-apps.grid.cyfronet.pl/repo/migrate.
| Anchor | ||||
|---|---|---|---|---|
|
The easiest way to check the correctness of the application is to verify it from the EPISODES Platform. Once, your application is created, you will be able to see it under User applications in My Apps Management tab (Figure 10 - note that this is the same view as in Figure 1, but now you should have an application listed). Note, that if you created the repository otherwise than with the EPISODES Platform wizard, using the Reload button might be necessary to refresh the list. Validating the application configuration might be also useful in such case (see more in Custom application configuration guide). To edit the application configuration similarly to EPISODES Platform wizard, use the Edit descriptors button.
Figure 10. The new application visible on the My Apps Management view within EPISODES Platform
If the application was configured correctly, it should now be visible also on the list under the Applications tab (see Figure 11). If it is not, this might mean, that there is something wrong with either its Application Definition or Application Description file - consider validating the application and checking the Common Issues guide. Otherwise, the final step is to run your application.
Figure 11. Application displayed correctly under the Applications tab
New application configuration
Important fields used in the wizard are briefly described below:
- Application Workbench name - the name of the application and the repository that will contain all application files,
- Programming language - the programming language which is used for the scripts used by the application,
- Function name - script name, the name of the main function that is executed after the application is started,
- Required tools - the list of the tools required by application to run, it should be in accordance with the scripting language and may optionally include other programs or toolboxes,
- Input files - it allows to add the input files that will be used by the application to acquire variables which are then used as arguments by the main function. If added, one must specify its Type,
- Input parameters - input parameters which are specified in this field are visible as the form in the application panel and are entered manually by the user,
- Outputs - the output file/files generated by the application. When added, one must provide its Output file name, Type and Format,
Add application description - checkbox that enables optional form for creating the application description;
For details on each field and all possible options that may be used in the application wizard, go to Custom application configuration.
Warning! After the create new application button is used the only option to edit the application is by modifying the Git/Gitea repository!
By clicking the create button the user applications list will be shown. The created application should be visible on the user's application list and in the applications tab. You may now check the repository created on Gitea by clicking </> CODE REPOSITORY button.
Figure 2. To go to the Gitea repository of the application use the marked button.
Creating a new application manually
Go to GITEA page and log in with your custom account or sign in with EPISODES Platform (authentication by Unity). After successfully logging to Gitea client first you need to create a new repository for the application. The two paths of creating the repository are shown on the figures below:
Figure 3. One of the way to create a new repository is by clicking the marked button.
Figure 4. The second way to create a new repository is to use the panel at the top right corner of the page.
Repository configuration
In the New Repository section only one field is required to fill: Repository Name (it may contain only alphanumeric, dash, undersore and dot characters). Other important but optional fields are described below:
- Owner - owner of the repository may be selected,
- Visibility - if repository is private it will be visible only to the owner and optionally selected organization members if they have rights (e.g. collaborators). Otherwise repository will be visible to everyone,
- Description - short description what repository is containing,
- Template - template repository may be selected (templates may be shared by team members),
- .gitignore - it allows to specify intentionally untracked files to ignore from a list of templates for common languages (by default it contains common artifacts generated by each language builder tool),
- License - it informs other users what they can do with code contained in the repository,
- Initialize Repository (Adds .gitignore, License and README) - only if the field is checked the elements listed in parentheses will be included to the repository
- Default Branch - default branch name may be specified,
- Signature Trust Model - here one can specify the trust model for signature verification,
- Template (Make repository template) - if ticked, the repository may serve as a template for new repositories in the future;
After filling fields and clicking Create Repository Button, you shall see a screen with a Git's Quick Guide and link for cloning the repository. For more information about working with Git please follow this link: Git Reference.
Figure 5. You may copy the link to the repository by clicking button on the right.
Related Documents
| Content by Label | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Overview
Content Tools