Initialize a new Tapis Actor project

This guide will demonstrate how to create a custom actor from scratch. It is assumed you are already familiar with how to Work with Actors. In this example, we will build a simple word count actor that counts and prints the number of words in a provided message.

We will demonstrate how to initialize an actor project from scratch.

Create a project “hello_world_actor”

To get started with creating an actor, running the tapis actors init command will fetch a very simple code skeleton you can fill in and deploy.

For example:

$ tapis actors init

| stage | message                                             |
| setup | Project path: ./new_actor                           |
| setup | CookieCutter variable name=new_actor                |
| setup | CookieCutter variable project_slug=new_actor        |
| setup | CookieCutter variable docker_namespace=reshg        |
| setup | CookieCutter variable docker_registry=e             |
| clone | Project path: ./new_actor                           |


There are many project templates you can start working with. See tapis actors init –list-templates for an up to date listing.

$ tapis actors init --list-templates
| id                 | name               | description                                            | level    |
| default            | Default            | Basic code and configuration skeleton                  | beginner |
| echo               | Echo               | Echo message                                           | beginner |
| hello_world        | Hello World        | Say Hello, World!                                      | beginner |
| sd2e_base          | sd2e_base          | Default reactor context for                            | beginner |
|                    |                    | docker://sd2e/reactors:python3                         |          |
| tacc_reactors_base | tacc_reactors_base | Default actor context for                              | beginner |
|                    |                    | docker://sd2e/reactors:python3                         |          |

To use one of these templates:

$ tapis actors init --template hello_world

Components of an Actor

The new_actor/ project would contain the following files:

$ tree ../new_actor/
├── Dockerfile
├── project.ini
├── config.yml
├── requirements.txt
├── secrets.jsonsample
└── message.jsonschema

Write the Actor Function

The script can be renamed to The python script is where the code for your main function can be found. An example of a functional actor that says “Hello, World” is:

"""Say Hello, World or the message received from user input"""
from agavepy.actors import get_context

# function to print the message
def say_hello_world(m):
"""Print message from user if present, else echo "Hello, World"""
    if m == " ":
        print("Actor says: Hello, World")
        print("Actor received message: {}".format(m))

def main():
"""Main entry to grab message context from user input"""
    context = get_context()
    message = context['raw_message']

if __name__ == '__main__':

This code makes use of the agavepy python library which we will install in the Docker container. The library includes an “actors” object which is useful to grab the message and other context from the environment. And, it can be used to interact with other parts of the Tapis platform. Add the above code to your file.

Define Requirements

The requirements.txt file may contain the dependencies required for a project. The default requirements.txt contains agavepy python package.

Create a Dockerfile

The only requirements are python and the agavepy python library, which is available through PyPi. These are mentioned in the requirements.txt file A bare-bones Dockerfile needs to satisfy those dependencies, add the actor python script, and set a default command to run the actor python script. The following lines should be present in your Dockerfile:

# pull base image
FROM python:3.7-alpine

# add requirements.txt to docker container
ADD requirements.txt /requirements.txt

# install requirements.txt
RUN pip3 install -r /requirements.txt

# add the python script to docker container

# command to run the python script
CMD ["python", "/"]


Creating small Docker images is important for maintaining actor speed and efficiency

Runtime Preparation

  1. Define secrets.json: Rename secrets.json.sample to secrets.json, and obtain the required values from the Infrastructure team for secrets.json.

  2. Define message.jsonschema: Define the Schema for Actor launch message.

Build and Push the Dockerfile

The Docker image must be pushed to a public repository in order for the actor to use it. Use the following Docker commands in your local actor folder to build and push to a repository that you have access to:

# Build and tag the image
$ docker build -t taccuser/hello-world:1.0 .
Sending build context to Docker daemon  4.096kB
Step 1/5 : FROM python:3.7-slim
Successfully built b0a76425e8b3
Successfully tagged taccuser/hello-world:1.0

# Push the tagged image to Docker Hub
$ docker push taccuser/hello-world:1.0
The push refers to repository []
1.0: digest: sha256:67cc6f6f00589d9ae83b99d779e4893a25e103d07e4f660c14d9a0ee06a9ddaf size: 1995

Create the Actor

Next, create an actor referring to the Docker repository above.

$ tapis actors create --repo taccuser/hello-world:1.0 \
                      -n hello-world \
                      -d "Actor to say Hello, World"
| Field          | Value                      |
| id             | NN5N0kGDvZQpA              |
| name           | hello-world                |
| owner          | taccuser                   |
| image          | taccuser/hello-world:1.0   |
| lastUpdateTime | 2021-07-14T22:25:06.171534 |
| status         | SUBMITTED                  |
| cronOn         | False                      |

After a few seconds, the actor should be in state “READY”, meaning it is ready to accept and process messages. Verbosely show the actor metadata to see that it’s status is “READY”, it is pointing to the correct docker image, and that it received the environment variables from environment.json:

$ tapis actors show -v NN5N0kGDvZQpA
 "id": "NN5N0kGDvZQpA",
 "name": "example-actor",
 "description": "Test actor that says Hello, World",
 "owner": "sgopal",
 "image": "tacc/hello-world:latest",
 "createTime": "2021-07-14T22:25:06.171Z",
 "lastUpdateTime": "2021-07-14T22:25:06.171Z",
 "defaultEnvironment": {},
 "gid": 862347,
 "hints": [],
 "link": "",
 "mounts": [],
 "privileged": false,
 "queue": "default",
 "stateless": true,
 "status": "READY",
 "statusMessage": " ",
 "token": true,
 "uid": 862347,
 "useContainerUid": false,
 "webhook": "",
 "cronOn": false,
 "cronSchedule": null,
 "cronNextEx": null,
 "_links": {
   "executions": "",
   "owner": "",
   "self": ""

Run a Test Execution

Finally, pass a message to the actor to run a test execution. The number of words in the message should be returned in the actor execution logs:

# Send a message to the word-count actor
$ tapis actors submit -m "Hello, World" NN5N0kGDvZQpA
| Field       | Value                               |
| executionId | NN5N0kGDvZQpA                       |
| msg         | Hello, World                        |

# List executions of the word-count actor
$ tapis actors execs list NN5N0kGDvZQpA
| executionId   | status   |
| N4xQ5WM5Np1X0 | COMPLETE |

# Get the logs from the completed actor execution
$ tapis actors execs logs NN5N0kGDvZQpA N4xQ5WM5Np1X0
Logs for execution N4xQ5WM5Np1X0
 Actor received message: Hello, World

The actor can also be run synchronously using tapis actors run:

$ tapis actors run -m "Hello, World" NN5N0kGDvZQpA
Actor received message: Hello, World

Next Steps

Remember to put your actor under version control. Use a .gitignore file to avoid accidentally committing anything that contains API keys or passwords.

Please refer to the Abaco Documentation for more information on creating and working with actors.