Public | Automated Build

Last pushed: 3 years ago
Short Description
Short description is empty for this repo.
Full Description


This project is a server with real-time bidirectional event-based communication,
used by Grounds to execute arbitry code within various
languages inside Docker containers.

grounds-exec support many languages and make it really trivial to add support
for other languages.

All you need is Docker 1.3+,
Docker Compose 1.1+ and
make to run this project inside Docker
containers with the same environment as in production.


This project is language agnostic, the only mandatory thing is to have Docker
images following the format described in this

Checkout this
to get more informations about how to add support for a new language stack.


grounds-exec is using This adds the ability
to run arbitrary code in real-time from a web browser.

Each run is executed inside a Docker container, which is destroyed at the end
of the run.

A container automatically timeouts 10 seconds after the beginning of a run.

If a run request is sent from the same client when a previous run request is
already running, this previous request will be gracefully interrupted.

Clone this project

git clone

Get into this project directory

cd grounds-exec

Build language stack images

make images

The first build takes a lot of time. If you want you can also pull official

make images-pull

If you want to push these images to your own repository:

REPOSITORY="<you repository>" make images-push

Set Docker remote API url

You need to specify a docker remote API url to connect with.

export DOCKER_URL=""

If your are using Docker API through https, your DOCKER_CERT_PATH will be
mounted has a volume inside the container.

Be careful: boot2docker enforces tls verification since version 1.3.

If you want to use a different Docker host to creates code runners inside
containers you can also specify DOCKER_RUNNERS_URL.

Currently both Docker hosts need to have the same ssl certificates. server

Start the server

make run

You can also run the server in the background:

make detach



If the server is already running:

make re

If you want New Relic metrics you can also specify:


e.g. NEWRELIC_LICENSE_KEY="<you license key>" NEWRELIC_APP_NAME="grounds-exec" make run

Connect to the server

You need to use a client to
connect with this server.

var client = io.connect('http:<docker host ip>:8080');

Send a run request

client.on('connect', function(data) {
    client.on('run', function(data){
    client.emit('run', { language: 'python2', code: 'print 42' });

Run response

  • Format:

      { stream: 'stream', chunk: 'chunk' }
  • Typical response:

      { stream: 'start',  chunk: '' }
      { stream: 'stdout', chunk: '42\n' }
      { stream: 'stderr', chunk: 'Error!\n' }
      { stream: 'status', chunk: 0 }

If an error occured during a run, you will receive:

{ stream: 'error', chunk: 'Error message' }

The server has a spam prevention against each run request. The minimum
delay between two run request is fixed to 0.5 seconds, otherwise you will
receive an error.


Tests will also run inside Docker containers with the same environment
as the CI server.

You need to pull the official ruby image to run the test suite:

docker pull grounds/exec-ruby

To run the test suite:

make test

To run specific test files or add a flag for mocha you
can specify TEST_OPTS:

TEST_OPTS="test/utils.js" make test


Before sending a pull request, please checkout the contributing


See authors file.


grounds-exec is licensed under the MIT License. See LICENSE for
full license text.

Docker Pull Command
Source Repository