Eclipse Che has a remote plug-in endpoint service to start VS Code Extensions and Che-Theia plug-ins in separate containers. Eclipse Che injects the remote plug-in endpoint binaries into each remote plug-in container. This service starts remote extensions and plug-ins defined in the plug-in meta.yaml file and connects them to the Che-Theia editor container.

The remote plug-in endpoint creates a plug-in API proxy between the remote plug-in container and the Che-Theia editor container. The remote plug-in endpoint is also an interceptor for some plug-in API parts, which it launches inside a remote sidecar container instead of an editor container. Examples: terminal API, debug API.

The remote plug-in endpoint executable command is stored in the environment variable of the remote plug-in container: PLUGIN_REMOTE_ENDPOINT_EXECUTABLE.

Eclipse Che provides two ways to start the remote plug-in endpoint with a sidecar image:

  • Defining a launch remote plug-in endpoint using a Dockerfile. To use this method, patch an original image and rebuild it.

  • Defining a launch remote plug-in endpoint in the plug-in meta.yaml file. Use this method to avoid patching an original image.

Defining a launch remote plug-in endpoint using Dockerfile

To start a remote plug-in endpoint, use the PLUGIN_REMOTE_ENDPOINT_EXECUTABLE environment variable in the Dockerfile.

Procedure

  • Start a remote plug-in endpoint using the CMD command in the Dockerfile:

    Dockerfile example
    FROM fedora:30

RUN dnf update -y && dnf install -y nodejs htop && node -v

RUN mkdir /home/user

ENV HOME=/home/user

RUN mkdir /projects \
    && chmod -R g+rwX /projects \
    && chmod -R g+rwX "${HOME}"

CMD ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}

  • Start a remote plug-in endpoint using the ENTRYPOINT command in the Dockerfile:

    Dockerfile example
    FROM fedora:30

RUN dnf update -y && dnf install -y nodejs htop && node -v

RUN mkdir /home/user

ENV HOME=/home/user

RUN mkdir /projects \
    && chmod -R g+rwX /projects \
    && chmod -R g+rwX "${HOME}"

ENTRYPOINT ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}

Using a wrapper script

Some images use a wrapper script to configure permissions. The script is defined it in the ENTRYPOINT command of the Dockerfile to configure permissions inside the container, and it script executes a main process defined in the CMD command of the Dockerfile.

Eclipse Che uses such images with a wrapper script to provide permission configurations on different infrastructures with advanced security, for example on OpenShift.

  • Example of a wrapper script:

    #!/bin/sh

set -e

export USER_ID=$(id -u)
export GROUP_ID=$(id -g)

if ! whoami >/dev/null 2>&1; then
    echo "${USER_NAME:-user}:x:${USER_ID}:0:${USER_NAME:-user} user:${HOME}:/bin/sh" >> /etc/passwd
fi

# Grant access to projects volume in case of non root user with sudo rights
if [ "${USER_ID}" -ne 0 ] && command -v sudo >/dev/null 2>&1 && sudo -n true > /dev/null 2>&1; then
    sudo chown "${USER_ID}:${GROUP_ID}" /projects
fi

exec "$@"

  • Example of a Dockerfile with a wrapper script:

    Dockefile example
    FROM alpine:3.10.2

ENV HOME=/home/theia

RUN mkdir /projects ${HOME} && \
    # Change permissions to let any arbitrary user
    for f in "${HOME}" "/etc/passwd" "/projects"; do \
      echo "Changing permissions on ${f}" && chgrp -R 0 ${f} && \
      chmod -R g+rwX ${f}; \
    done

ADD entrypoint.sh /entrypoint.sh

ENTRYPOINT [ "/entrypoint.sh" ]
CMD ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}

    In this example, the container launches the /entrypoint.sh script defined in the ENTRYPOINT command of the Dockerfile. The script configures the permissions and executes the command using exec $@. CMD is the argument for ENTRYPOINT, and the exec $@ command calls ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}. A remote plug-in endpoint then starts in the container after permission configuration.

Defining a launch remote plug-in endpoint in a meta.yaml file

Use this method to re-use images to start remote a plug-in endpoint without modifications.

Procedure

Modify the plug-in meta.yaml file properties command and args:

  • command - Eclipse Che uses to override Dockerfile#ENTRYPOINT.

  • args - Eclipse Che uses to override Dockerfile#CMD.

  • Example of a YAML file with the command and args properties modified:

    apiVersion: v2
category: Language
description: "Typescript language features"
displayName: Typescript
firstPublicationDate: "2019-10-28"
icon: "https://www.eclipse.org/che/images/logo-eclipseche.svg"
name: typescript
publisher: che-incubator
repository: "https://github.com/Microsoft/vscode"
title: "Typescript language features"
type: "VS Code extension"
version: remote-bin-with-override-entrypoint
spec:
  containers:
    - image: "example/fedora-for-ts-remote-plugin-without-endpoint:latest"
      memoryLimit: 512Mi
      name: vscode-typescript
      command:
        - sh
        - -c
      args:
        - ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}
  extensions:
    - "https://github.com/che-incubator/ms-code.typescript/releases/download/v1.35.1/che-typescript-language-1.35.1.vsix"

  • Modify args instead of command to use an image with a wrapper script pattern and to keep a call of the entrypoint.sh script:

    apiVersion: v2
category: Language
description: "Typescript language features"
displayName: Typescript
firstPublicationDate: "2019-10-28"
icon: "https://www.eclipse.org/che/images/logo-eclipseche.svg"
name: typescript
publisher: che-incubator
repository: "https://github.com/Microsoft/vscode"
title: "Typescript language features"
type: "VS Code extension"
version: remote-bin-with-override-entrypoint
spec:
  containers:
    - image: "example/fedora-for-ts-remote-plugin-without-endpoint:latest"
      memoryLimit: 512Mi
      name: vscode-typescript
      args:
        - sh
        - -c
        - ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}
  extensions:
    - "https://github.com/che-incubator/ms-code.typescript/releases/download/v1.35.1/che-typescript-language-1.35.1.vsix"

    Eclipse Che calls the entrypoint.sh wrapper script defined in the ENTRYPOINT command of the Dockerfile. The script executes [ ‘sh’, ‘-c”, ‘ ${PLUGIN_REMOTE_ENDPOINT_EXECUTABLE}’ ] using the exec “$@” command.

To execute a service when starting the container and also to start a remote plug-in endpoint, use meta.yaml with modified command and args properties. Start the service, detach the process, and start the remote plug-in endpoint, and they then work in parallel.