Docs
Search…
Hello, World!
In this step-by-step tutorial you will create your first customize module from scratch and move it online to the APEER platform.
As part of this tutorial, you will be creating a module that takes in an empty text file and returns a copy with the line "Hello, World!" written on it. This tutorial is to simply highlight the main steps for creating a basic module, it will not go into the details of each part. You can get further understanding of the platform by completing the following tutorials.

Step #1: Create a new module

First of all we need to create a Git credentials to manage your module's Git repository and source code. Just select a username and password of your choice and click 'Update'.
Before we start right into the code development, we first have to create a new module on the APEER platform.
Please note that your steps slightly differ from what is shown in the following video. Those will be written below.
Steps required:
  • Login to your APEER account and navigate to ‘My Modules’ (found under ‘My Workspace’)
  • Click on 'Add New Module' (large blue rectangular box with a + sign)
  • Name your module 'Hello, World!' and select ‘Empty Module’ from the drop down
  • Click 'Create Now'

Step #2: Clone (copy) the module onto your computer

At the moment we only created a new empty module, which is stored in a Git repository on APEER. To get access to the source code, we need to download our module. To do so, APEER provides the necessary information of your module git repository.
  • Find 'Git Credentials' section on your new module page. If you accidentally navigate away, you can get back by going to 'My Modules' and clicking on the module you just created
  • If you want to change your Git credentials: Enter a username and password for your Git Credentials and hit the 'Update' button
You need to remember these credentials to download and upload the code to or from your machine using Git. You can update these credentials from your APEER account any time.
  • Copy the link next to Git credentials, which is the unique link for your module’s code
  • Create a new project folder on your machine where you want to store the git repository of your module
  • Open the terminal on your machine and move inside the project folder with cd Path/to/folder
  • Type git clone and paste your previously copied link
  • If prompt up enter your Git credentials
The Git repository of your module will now be downloaded.

Step #3: Basic module structure

In order for your module to work a minimum of 5 files are needed:
  • hello_world.py is the primary python file that contains the code for your module
  • apeer_main.py is the entry python file for Docker
  • requirements.txt contains all libraries that need to be installed in the Docker container
  • module_specification.json contains input and output parameters for your module
  • Dockerfile is responsible for running your Docker container on APEER
In order to have a comprehensive overview of all the different files required you should read about the Python Project Structure.
Create those 5 files inside your project folder. You can do it the same way you would create a simple text file, just make sure the names and the extensions are the same as shown above. We will write the necessary code inside each one in this order.

Step #4: Write your primary python script

Here is the code for your primary python script. It takes in an input , which in our case is an empty text file, writes "Hello, World!" in it and then sends it back as an output.
1
from shutil import copyfile
2
3
def execute(input):
4
file_name = "hello_world.txt"
5
copyfile(input, file_name)
6
f = open(file_name, "w")
7
f.write("Hello, World!")
8
f.close()
9
10
return {'Output': file_name}
Copied!

Step #5: apeer_main.py

This is the entry python file for the Docker. This file calls the main file with Python code and executes it using the parameters defined here. Depending on the complexity of your module you will make minor edits to this file, but overall it usually keeps the same structure.
1
from apeer_dev_kit import adk
2
import hello_world
3
4
if __name__ == "__main__":
5
inputs = adk.get_inputs()
6
7
outputs = hello_world.execute(inputs['Input'])
8
9
adk.set_file_output('Output', outputs['Output'])
10
adk.finalize()
Copied!

Step #6: requirements.txt

This file contains all the libraries that need to be installed within the container (see Dockerfile).
1
apeer-dev-kit>=1.0.6,<2
Copied!

Step #7: module_specification.json

In order to enable the Docker container of your module to be connected to other modules, it is necessary to add a module_specification.json file.
Step by step (doing it right)
Copy & paste (quick and dirty)
The following video shows you how you can edit the inputs/outputs of your module using the apeer interface. It can then generate a JSON file which you can download and add to your project folder.
Please note that the steps shown in the following video are slightly different than the ones you will have to make.
Steps required:
  • Go to your module site on APEER
  • Click on 'Generate Module Specifications'
  • Click 'add Input'
  • Name your input 'Input'
  • Under 'Input Type' select 'File'
  • Under 'Supported File Type' type in 'txt'
  • Click 'add Output'
  • Name your input 'Output'
  • Under 'Output Type' select 'File'
  • Under 'Supported File Type' type in 'txt'
  • Don't change 'Module Requirements'
  • Click 'Download' and Copy the content of this file in your module_specification.json file inside your project folder
1
{
2
"spec": {
3
"inputs": {
4
"Input": {
5
"type:file": {
6
"format": "txt"
7
}
8
}
9
},
10
"outputs": {
11
"Output": {
12
"type:file": {
13
"format": "txt"
14
}
15
}
16
}
17
},
18
"ui": {
19
"inputs": {
20
"Input": {
21
"label": "Input",
22
"index": 1,
23
"widget:none": null
24
}
25
},
26
"outputs": {
27
"Output": {
28
"label": "Output",
29
"index": 1
30
}
31
}
32
}
33
}
Copied!

Step #8: Dockerfile

The Dockerfile is what's going to generate the container that is going to be sent to the platform. It copies the apeer_main, hello_world python files and the json file for module specifications.
1
# The dockerfile begins with defining an image FROM which the build process starts.
2
# Since our module is based on python 3.0, we use python:3 as our base image.
3
# You can find trusted docker contains at https://store.docker.com/.
4
FROM python:3.6
5
6
# WORKDIR changes the active directory of the container to a specific location.
7
# In case you need to run commands from or in a particular location.
8
WORKDIR /usr/src/app
9
10
# Herje we copy the requirements.txt file and install all the required external libraries
11
COPY ./requirements.txt .
12
RUN pip install --no-cache-dir -r requirements.txt
13
14
# Here we are copying all our files to the root directory of the container
15
COPY ./apeer_main.py .
16
COPY ./hello_world.py .
17
COPY ./module_specification.json .
18
19
# In this example, we would like to run our python command when the container starts.
20
ENTRYPOINT [ "python", "./apeer_main.py" ]
Copied!

Step #9: Push all files to Apeer

Open the command prompt, while in the working directory type:
  • git add --all (this adds all files in the directory to local git)
  • git commit -m “Write any message here” (this commits all your changes locally)
  • git push (this pushes all changes to the platform. You may be asked to provide your Git credentials)
Read more about how to use Git @APEER

Step #10: Testing you module

  • On your Machine, create a blank text file 'hello_world.txt'
  • On the website, under 'My Workplace' > 'My Modules' select your newly built module
  • Click on the bleu button 'Create Workflow'
  • Name it 'Hello World!'
  • Click on the 'Define Input' module and choose to 'Upload files'
  • Choose the previously created text file
  • Click on Save
  • Link the Input module to the 'Hello, World!' module like so
  • Save your workflow
  • Click on the button 'Run'
  • Click on the next button 'run'
  • Your workflow should now be running
  • If everything worked fine, the banner should turn green. Give a name to your results, eg: 'Hello, World!'
  • You can now check the resulting file by clicking on the 'Preview' icon or downloading it.

Fast lane for impatient coders ;)

hello_world.py
apeer_main.py
module_specification.json
Dockerfile
requirements.txt
1
from shutil import copyfile
2
3
def execute(input):
4
file_name = "hello_world.txt"
5
copyfile(input, file_name)
6
f = open(file_name, "w")
7
f.write("Hello, World!")
8
f.close()
9
10
return {'Output': file_name}
Copied!
1
from apeer_dev_kit import adk
2
import hello_world
3
4
if __name__ == "__main__":
5
inputs = adk.get_inputs()
6
7
outputs = hello_world.execute(inputs['Input'])
8
9
adk.set_file_output('Output', outputs['Output'])
10
adk.finalize()
Copied!
1
{
2
"spec": {
3
"inputs": {
4
"Input": {
5
"type:file": {
6
"format": "txt"
7
}
8
}
9
},
10
"outputs": {
11
"Output": {
12
"type:file": {
13
"format": "txt"
14
}
15
}
16
}
17
},
18
"ui": {
19
"inputs": {
20
"Input": {
21
"label": "Input",
22
"index": 1,
23
"widget:none": null
24
}
25
},
26
"outputs": {
27
"Output": {
28
"label": "Output",
29
"index": 1
30
}
31
}
32
}
33
}
Copied!
1
# The dockerfile begins with defining an image FROM which the build process starts.
2
# Since our module is based on python 3.0, we use python:3 as our base image.
3
# You can find trusted docker contains at https://store.docker.com/.
4
FROM python:3.6
5
6
# WORKDIR changes the active directory of the container to a specific location.
7
# In case you need to run commands from or in a particular location.
8
WORKDIR /usr/src/app
9
10
# Here we are copying all our files to the root directory of the container
11
COPY ./apeer_main.py .
12
COPY ./hello_world.py .
13
COPY ./module_specification.json .
14
COPY ./requirements.txt .
15
16
# Include this, if you need Matplotlib to generate the output image
17
#RUN mkdir -p /root/.config/matplotlib
18
#RUN echo "backend : Agg" > /root/.config/matplotlib/matplotlibrc
19
20
RUN pip install -r requirements.txt
21
22
# CMD command is similar to RUN. However unlike RUN, CMD is not executed during build, but when a container is instantiated.
23
# Therefore, it should be considered as an initial, default command that gets executed when container starts.
24
# In this example, we would like to run our python command when the container starts.
25
ENTRYPOINT [ "python", "./apeer_main.py" ]
Copied!
1
apeer-dev-kit>=1.0.6,<2
Copied!

You couldn't find all the information you need? Contact us!

If you need help, just check out our FAQ. For any further questions please contact us at [email protected] or have a look at How-tos section in our blog or follow us on Twitter to stay up to date.
Last modified 1yr ago