Support custom IDEs provided through docker images

[meysholdt]

Since we now have the foundation in place to install a custom IDE in Gitpod using a Docker Image, It would be great to have a an example and docs that explain the minimal requirements Gitpod imposes on such an image.

[csweichel]

A rough, and still changing list of requirements we have towards IDE images:

• all static assets that we need to serve before the workspace pod is up and running MUST be in the very first layer
• there must be an executable file in /ide/startup.sh that's executed to start the IDE itself. This can be changed in the IDE supervisor config (see below).
• no system-folder must be overwritten, e.g. WORKDIR /usr/bin possibly creates an empty /usr/bin directory which would shadow the actual /usr/bin in the workspace.

IDE supervisor config

IDEs can provide some configuration to customise supervisor's behaviour. This file is expected in /ide/supervisor-ide-config.json and may look like this:

{
  "entrypoint": "/ide/startup.sh",
  "readinessProbe": {
    "type": "http",
    "http": {
      "path": "static/manifest.json"
    }
  }
}

The entrypoint configures the executable that get's run when starting the IDE.
The readinessProbe configures a probe that determines when the IDE is actually running. Right now we only support http probes which attempt a GET http://localhost:<ide-port>/<path> every five seconds. If that request returns 200 OK we consider the IDE running. If there's no probe configured, we consider the IDE running right after it got started (i.e. the entrypoint was executed).

Environment Variables coming from Gitpod

IDEs are expected to run on a particular port, specifically the one indicated on the GITPOD_THEIA_PORT environment variable. Expect this name to change in the near future.

Environment Variables coming from the IDE image

IDE images can contribute environment variables to a workspace.
The details are work in progress.

[csweichel]

We might want to introduce a linter for images that can verify those requirements. In its first iteration that linter would just be a development tool, but could conceivably be integrated into the system as a whole.

Also, we should look at ways for finding good defaults to relax those constraints over time.

[akosyakov]

IDE should have index.html and integrate supervisor as described in

gitpod/components/supervisor/frontend/src/index.ts

Lines 7 to 11 in c749c27

	/**
	* <script type="text/javascript" src="/_supervisor/frontend/main.js" charset="utf-8"></script> should be inserted to index.html as first body script,
	* all other IDE scripts should go afterwards, head element should not have scripts
	*/

is another requirement.

[csweichel]

First step would to be produce a working image for another IDE/editor, e.g. vim or https://github.com/JetBrains/projector-docker

[svenefftinge]

Let's do Theia as the first step.