grounds/grounds-exec repository overview

⁠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

⁠Build language stack images

make images

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

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="http://127.0.0.1:2375"

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

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

⁠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

⁠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' }
  

  Copy

• Typical response:

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

  Copy

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.