Skip to content

Tutorial: Connect a remote machine to the Web IDE (FREE ALL)

FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can disable the feature flag named vscode_web_ide. On GitLab.com, this feature is available. The feature is not ready for production use.

This tutorial shows you how to:

  • Create a development environment outside of GitLab.
  • Connect a remote machine to the Web IDE.

To connect a remote machine to the Web IDE, you'll:

  1. Generate Let's Encrypt certificates.
  2. Connect a development environment to the Web IDE.

Prerequisites

  • A remote virtual machine with root access
  • A domain address resolving to that machine
  • Docker installation

Generate Let's Encrypt certificates

To generate Let's Encrypt certificates:

  1. Create an A record to point a domain to your remote machine (for example, from example.remote.gitlab.dev to 10.0.2.2).

  2. Install Certbot to enable HTTPS:

    sudo apt-get update
sudo apt-get install certbot

  3. Generate the certificates:

    export EMAIL="YOUR_EMAIL@example.com"
export DOMAIN="example.remote.gitlab.dev"

certbot -d "${DOMAIN}" \
  -m "${EMAIL}" \
  --config-dir ~/.certbot/config \
  --logs-dir ~/.certbot/logs \
  --work-dir ~/.certbot/work \
  --manual \
  --preferred-challenges dns certonly

Now that you've generated the certificates, it's time to create and connect a development environment.

Connect a development environment to the Web IDE

To connect a development environment to the Web IDE:

  1. Create a development environment:

    export CERTS_DIR="/home/ubuntu/.certbot/config/live/${DOMAIN}"
export PROJECTS_DIR="/home/ubuntu"

docker run -d \
  --name my-environment \
  -p 3443:3443 \
  -v "${CERTS_DIR}/fullchain.pem:/gitlab-rd-web-ide/certs/fullchain.pem" \
  -v "${CERTS_DIR}/privkey.pem:/gitlab-rd-web-ide/certs/privkey.pem" \
  -v "${PROJECTS_DIR}:/projects" \
  registry.gitlab.com/gitlab-org/remote-development/gitlab-rd-web-ide-docker:0.2-alpha \
  --log-level warn --domain "${DOMAIN}" --ignore-version-mismatch

    The new development environment starts automatically.

  2. Fetch a token:

    docker exec my-environment cat TOKEN

  3. Configure a remote connection.

Configure a remote connection

To configure a remote connection from the Web IDE:

  1. Open the Web IDE.
  2. On the menu bar, select View > Terminal or press Control+`.
  3. In the terminal panel, select Configure a remote connection.
  4. Enter the URL for the remote host including the port (for example, yourdomain.com:3443).
  5. Enter the project path.
  6. Enter the token you've fetched.

Alternatively, you can pass the parameters from a URL and connect directly to the Web IDE:

  1. Run this command:

    echo "https://gitlab-org.gitlab.io/gitlab-web-ide?remoteHost=${DOMAIN}:3443&hostPath=/projects"

  2. Go to that URL and enter the token you've fetched.

You've done it! Your development environment now runs as a remote host that's connected to the Web IDE.

Related topics