grounds-exec

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.

Languages

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

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

Prerequisite

grounds-exec is using socket.io. 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 https://github.com/grounds/grounds-exec.git

Get into this project directory

cd grounds-exec

Get official images

Official Grounds language stack images are available on the Docker hub Grounds organization.

e.g. To pull latest Ruby image:

docker pull grounds/exec-ruby:latest

Warning: latest tag on the Docker hub matches the master branch of grounds-images.

Docker configuration

By default, the code runner will use your Docker host configuration to creates containers.

If you want to use a different Docker host to creates code runners inside containers you can also specify DOCKER_HOST_RUNNERS. Language stack images must be available on this host.

If you want to use SSL for both Docker hosts, they must share the same ssl certificates.

Socket.io server

Start the server

make run

You can also run the server in the background:

make detach

Or:

make

If the server is already running:

make re

If you want New Relic metrics you can also specify:

• NEWRELIC_LICENSE_KEY
• NEWRELIC_APP_NAME

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

If you want the server to look for custom Docker images, you can specify in your env:

• TAG: Image tag (default: latest).
• REPOSITORY: Image repository (default: grounds).

REPOSITORY and TAG can be changed for convenience, however we strongly recommend to use our official images with the latest tag incremental version.

Connect to the server

You need to use a socket.io 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){
        console.log(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

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

Contributing

Before sending a pull request, please checkout the contributing guidelines.

Authors

See authors file.

Licensing

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