Open Runtimes Executor 🤖

---

Executor for Open Runtimes, a runtime environments for serverless cloud computing for multiple coding languages.

Executor is responsible for providing HTTP API for creating and executing Open Runtimes. Executor is stateless and can be scaled horizontally when a load balancer is introduced in front of it. You could use any load balancer but we highly recommend using Open Runtimes Proxy for it's ease of setup with Open Runtimes Executor.

Features

• Flexibility - Configuring custom image lets you use any runtime for your functions.
• Performance - Coroutine-style HTTP servers allows asynchronous operations without blocking. We. Run. Fast! ⚡
• Open Source - Released under the MIT license, free to use and extend.

Getting Started

1. Pull Open Runtimes Executor image:

docker pull openruntimes/executor

2. Create docker-compose.yml file:

version: '3'services:
openruntimes-executor:
container_name: openruntimes-executorhostname: executorstop_signal: SIGINTimage: openruntimes/executornetworks:
openruntimes-runtimes:
ports:
- 9900:80volumes:
- /var/run/docker.sock:/var/run/docker.sock
- openruntimes-builds:/storage/builds:rw
- openruntimes-functions:/storage/functions:rw
- /tmp:/tmp:rw
- ./functions:/storage/functions:rwenvironment:
- OPR_EXECUTOR_ENV
- OPR_EXECUTOR_IMAGES
- OPR_EXECUTOR_CONNECTION_STORAGE
- OPR_EXECUTOR_CONNECTION_BUILD_CACHE_STORAGE
- OPR_EXECUTOR_INACTIVE_THRESHOLD
- OPR_EXECUTOR_MAINTENANCE_INTERVAL
- OPR_EXECUTOR_NETWORK
- OPR_EXECUTOR_SECRET
- OPR_EXECUTOR_DOCKER_HUB_USERNAME
- OPR_EXECUTOR_DOCKER_HUB_PASSWORD
- OPR_EXECUTOR_RUNTIME_VERSIONS
- OPR_EXECUTOR_RETRY_ATTEMPTS
- OPR_EXECUTOR_RETRY_DELAY_MS
- OPR_EXECUTOR_IMAGE_PULLnetworks:
openruntimes-runtimes:
name: openruntimes-runtimesvolumes:
openruntimes-builds:
openruntimes-functions:

Notice we added bind to local ./functions directory. That is only nessessary for this getting started, since we will be executing our custom function.

3. Create .env file:

OPR_EXECUTOR_ENV=development
OPR_EXECUTOR_IMAGES=openruntimes/php:v5-8.3
OPR_EXECUTOR_CONNECTION_STORAGE=file://localhost
OPR_EXECUTOR_CONNECTION_BUILD_CACHE_STORAGE=
OPR_EXECUTOR_INACTIVE_THRESHOLD=60
OPR_EXECUTOR_MAINTENANCE_INTERVAL=60
OPR_EXECUTOR_NETWORK=openruntimes-runtimes
OPR_EXECUTOR_SECRET=executor-secret-key
OPR_EXECUTOR_DOCKER_HUB_USERNAME=
OPR_EXECUTOR_DOCKER_HUB_PASSWORD=
OPR_EXECUTOR_RUNTIME_VERSIONS=v5
OPR_EXECUTOR_RETRY_ATTEMPTS=5
OPR_EXECUTOR_RETRY_DELAY_MS=500

OPR_EXECUTOR_CONNECTION_STORAGE takes a DSN string that represents a connection to your storage device. Every scheme but file and local requires a host. For example:

Storage	DSN
Local filesystem	file://localhost
AWS S3	s3://access_key:access_secret@bucket_name.s3.us-east-1.amazonaws.com?region=us-east-1
S3-compatible (MinIO, Garage, etc.)	s3://access_key:access_secret@minio:9000/bucket_name?region=us-east-1&insecure=true
S3-compatible, endpoint given outright	s3://access_key:access_secret@localhost/bucket_name?region=us-east-1&url=http%3A%2F%2Fminio%3A9000

The DSN resolves to an endpoint of scheme://host[:port][/bucket], and every object key hangs off it. insecure=true makes that scheme http, and the port is used as given. The bucket is the path of the DSN, and it reaches the endpoint exactly once: it is appended for path-style addressing, and left alone where the endpoint already names it, either as the leading label of the host (AWS S3, DigitalOcean Spaces, Backblaze, Linode and Wasabi all address their buckets that way) or as the path of a url. url replaces the scheme, host and port, so the last two rows above address the same object.

A DSN that cannot be parsed, or whose scheme has no device, is rejected rather than quietly falling back to the local filesystem. Ask for local storage with file:// or local://, or leave the variable empty.

For backwards compatibility, executor also supports OPR_EXECUTOR_STORAGE_* variables as replacement for OPR_EXECUTOR_CONNECTION_STORAGE, as seen in Appwrite repository.

4. Start Docker container:

docker compose up -d

5. Prepare a function we will ask executor to run:

mkdir -p functions &&cd functions && mkdir -p php-function &&cd php-function
printf"<?\nreturn function(\$req, \$res) {\n \$res->json([ 'n' => \mt_rand() / \mt_getrandmax() ]);\n};"> index.php
tar -czf ../my-function.tar.gz .cd .. && rm -r php-function

This created my-function.tar.gz that includes index.php with a simple Open Runtimes script.

5. Send a HTTP request to executor server:

curl -H "authorization: Bearer executor-secret-key" -H "Content-Type: application/json" -X POST http://localhost:9900/v1/runtimes/my-function/execution -d '{"image":"openruntimes/php:v2-8.0","source":"/storage/functions/my-function.tar.gz","entrypoint":"index.php"}'

6. Stop Docker containers:

docker compose down

API Endpoints

Method	Endpoint	Description	Params
GET	/v1/runtimes/{runtimeId}/logs	Get live stream of logs of a runtime	JSON
POST	/v1/runtimes	Create a new runtime server	JSON
GET	/v1/runtimes	List currently active runtimes	X
GET	/v1/runtimes/{runtimeId}	Get a runtime by its ID	JSON
DELETE	/v1/runtimes/{runtimeId}	Delete a runtime	JSON
POST	/v1/runtimes/{runtimeId}/executions	Create an execution	JSON
GET	/v1/health	Get health status	X

/v1/runtimes/{runtimeId}/logs

Param	Type	Description	Required	Default
runtimeId	string	Runtime unique ID	✅
timeout	string	Maximum logs timeout in seconds		'600'

/v1/runtimes

Param	Type	Description	Required	Default
runtimeId	string	Runtime unique ID	✅
image	string	Base image name of the runtime	✅
entrypoint	string	Entrypoint of the code file		' '
source	string	Path to source files		' '
destination	string	Destination folder to store runtime files into		' '
variables	json	Environment variables passed into runtime		[ ]
runtimeEntrypoint	string	Commands to run when creating a container. Maximum of 100 commands are allowed, each 1024 characters long.		' '
command	string	Commands to run after container is created. Maximum of 100 commands are allowed, each 1024 characters long.		' '
cacheKey	string	Optional key for sharing build caches. Must start with a letter or number. Allowed characters are letters, numbers, dots, underscores, and hyphens.		' '
timeout	integer	Commands execution time in seconds		600
remove	boolean	Remove a runtime after execution		false
cpus	float	Maximum CPU cores runtime can utilize		1
memory	integer	Container RAM memory in MBs		512
version	string	Runtime Open Runtime version (allowed values: 'v2', 'v5')		'v5'

/v1/runtimes/{runtimeId}

Param	Type	Description	Required	Default
runtimeId	string	Runtime unique ID	✅

/v1/runtimes/{runtimeId}/executions

Param	Type	Description	Required	Default
runtimeId	string	The runtimeID to execute	✅
body	string	Data to be forwarded to the function, this is user specified.		' '
path	string	Path from which execution comes		'/'
method	array	Path from which execution comes		'GET'
headers	json	Headers passed into runtime		[ ]
timeout	integer	Function maximum execution time in seconds		15
image	string	Base image name of the runtime		' '
source	string	Path to source files		' '
entrypoint	string	Entrypoint of the code file		' '
variables	json	Environment variables passed into runtime		[ ]
cpus	floats	Maximum CPU cores runtime can utilize		1
memory	integer	Container RAM memory in MBs		512
version	string	Runtime Open Runtime version (allowed values: 'v2', 'v5')		'v5'
runtimeEntrypoint	string	Commands to run when creating a container. Maximum of 100 commands are allowed, each 1024 characters long.		' '

Environment variables

Variable name	Description
OPR_EXECUTOR_ENV	Environment mode of the executor, ex. development
OPR_EXECUTOR_IMAGES	Comma-separated list of supported images (ex: openruntimes/php:v5-8.1,openruntimes/php:v2-8.1,..).
OPR_EXECUTOR_CONNECTION_STORAGE	DSN string that represents a connection to your storage device, ex: file://localhost for local storage
OPR_EXECUTOR_CONNECTION_BUILD_CACHE_STORAGE	Optional DSN string for build cache artifacts. Defaults to OPR_EXECUTOR_CONNECTION_STORAGE when empty
OPR_EXECUTOR_INACTIVE_THRESHOLD	Threshold time (in seconds) for detecting inactive runtimes, ex: 60
OPR_EXECUTOR_MAINTENANCE_INTERVAL	Interval (in seconds) at which the Executor performs maintenance tasks, ex: 60
OPR_EXECUTOR_NETWORK	Network used by the executor for runtimes, ex: openruntimes-runtimes
OPR_EXECUTOR_SECRET	Secret key used by the executor for authentication
OPR_EXECUTOR_DOCKER_HUB_USERNAME	Username for Docker Hub authentication (if applicable)
OPR_EXECUTOR_DOCKER_HUB_PASSWORD	Password for Docker Hub authentication (if applicable)
OPR_EXECUTOR_RUNTIME_VERSIONS	Version tag for runtime environments, ex: v5
OPR_EXECUTOR_RETRY_ATTEMPTS	Number of retry attempts for failed executions, ex: 5
OPR_EXECUTOR_RETRY_DELAY_MS	Delay (in milliseconds) between retry attempts, ex: 500

Contributing

All code contributions - including those of people having commit access - must go through a pull request and be approved by a core developer before being merged. This is to ensure a proper review of all the code.

We truly ❤️ pull requests! If you wish to help, you can learn more about how you can contribute to this project in the contribution guide.

Security

For security issues, kindly email us at security@appwrite.io instead of posting a public issue on GitHub.

Follow Us

Join our growing community around the world! See our official Blog. Follow us on Twitter, Facebook Page, Facebook Group , Dev Community or join our live Discord server for more help, ideas, and discussions.

License

This repository is available under the MIT License.