Home

Awesome

docker-run

Overview

docker-run provides a http api for running untrusted code inside transient docker containers. For every run request a new container is started and deleted. The payload is passed to the container by attaching to it and writing it to stdin. The result is read from stdout. The communication with the docker daemon happens via it's api over the unix socket. This is used to run code on glot.io.

Api

ActionMethodRouteRequires token
Get service infoGET/No
Get docker infoGET/versionYes
Run codePOST/runYes

Docker images

When a run request is posted to docker-run it will create a new temporary container. The container is required to listen for a json payload on stdin and must write the run result to stdout as a json object containing the properties: stdout, stderr and error. The docker images used by glot.io can be found here.

Performance

The following numbers were obtained using glot-images on a 5$ linode vm running 'Hello World' with httpstat multiple times locally on the same host and reading the numbers manually. Not scientific numbers, but it will give an indication of the overhead involved.

LanguageMinMax
Python250 ms350 ms
C330 ms430 ms
Haskell500 ms700 ms
Java2000 ms2200 ms

With gVisor (optional)

LanguageMinMax
Python450 ms570 ms
C1300 ms1500 ms
Haskell1760 ms2060 ms
Java4570 ms4800 ms

Security

Docker containers are not as secure as a vm and there has been weaknesses in the past where people have been able to escape a container in specific scenarios. The recommended setup is to store any database / user data / secrets on a separate machine then the one that runs docker + docker-run, so that if anyone is able to escape the container it will limit what they get access to. That said, glot.io has been running untrusted code in docker containers since 2015 without any issues.

Depending on your use-case you should also consider to:

Installation instructions

FAQ

Q: How is fork bombs handled?

A: The number of processes a container can create can be set with the DOCKER_CONTAINER_ULIMIT_NPROC_HARD variable.

Q: How is infinite loops handled?

A: The container will be killed when the RUN_MAX_EXECUTION_TIME value is reached.

Q: How is large output handled?

A: Docker-run will stop reading the output from the container when it has read the number of bytes defined in RUN_MAX_OUTPUT_SIZE.

Q: How is high memory usage handled?

A: The max memory for a container can be set with the DOCKER_CONTAINER_MEMORY variable.

Environment variables

Required

Variable nameTypeDescription
SERVER_LISTEN_ADDR<ipv4 address>Listen ip
SERVER_LISTEN_PORT1-65535Listen port
SERVER_WORKER_THREADS<integer>How many simultaneous requests that should be processed
API_ACCESS_TOKEN<string>Access token is required in the request to run code
DOCKER_UNIX_SOCKET_PATH<filepath>Path to docker unix socket
DOCKER_UNIX_SOCKET_READ_TIMEOUT<seconds>Read timeout
DOCKER_UNIX_SOCKET_WRITE_TIMEOUT<seconds>Write timeout
DOCKER_CONTAINER_HOSTNAME<string>Hostname inside container
DOCKER_CONTAINER_USER<string>User that will execute the command inside the container
DOCKER_CONTAINER_MEMORY<bytes>Max memory the container is allowed to use
DOCKER_CONTAINER_NETWORK_DISABLED<bool>Enable or disable network access from the container
DOCKER_CONTAINER_ULIMIT_NOFILE_SOFT<integer>Soft limit for the number of files that can be opened by the container
DOCKER_CONTAINER_ULIMIT_NOFILE_HARD<integer>Hard limit for the number of files that can be opened by the container
DOCKER_CONTAINER_ULIMIT_NPROC_SOFT<integer>Soft limit for the number of processes that can be started by the container
DOCKER_CONTAINER_ULIMIT_NPROC_HARD<integer>Hard limit for the number of processes that can be started by the container
DOCKER_CONTAINER_CAP_DROP<space separated list>List of capabilies to drop
RUN_MAX_EXECUTION_TIME<seconds>Maximum number of seconds a container is allowed to run
RUN_MAX_OUTPUT_SIZE<bytes>Maximum number of bytes allowed from the output of a run

Optional

Variable nameTypeDescription
DOCKER_CONTAINER_READONLY_ROOTFS<bool>Mount root as read-only (recommended)
DOCKER_CONTAINER_TMP_DIR_PATH<filepath>Will add a writeable tmpfs mount at the given path
DOCKER_CONTAINER_TMP_DIR_OPTIONS<string>Mount options for the tmp dir (default: rw,noexec,nosuid,size=65536k)
DOCKER_CONTAINER_WORK_DIR_PATH<filepath>Will add a writeable tmpfs mount at the given path
DOCKER_CONTAINER_WORK_DIR_OPTIONS<string>Mount options for the work dir (default: rw,exec,nosuid,size=131072k)
DEBUG_KEEP_CONTAINER<bool>Don't remove the container after run is completed (for debugging)