Dr. Stefan Winkler
freier Softwareentwickler und IT-Berater

This article is part of a series to help newcomers to get started with Eclipse Theia development by setting up a local docker-based development environment for Theia.

So here it is. After over 10 years of Eclipse development, I wanted to get my hands dirty on something entirely new. I have followed the developments of Orion, Che, and Theia for a long time, but only from a distance; and I just didn’t have the time to actually try out, let alone to get involved with, these projects.

I have used Gitpod a few times, but merely to have a quick look into a GitHub repository when I didn’t have a local development environment and didn’t want to get one up and running.

Yet, I have noticed an increasing interest from my customers in web-based environments and so, I wanted to finally play around with Eclipse Theia.

But how? I have found this article which provides several options to run Eclipse Theia in different ways, but none of those options really hit the spot for me. I wanted to run a Theia instance in my browser, so Theia Blueprint was not an option. I wanted to be able to work offline, so using Gitpod was not possible. And I didn’t want to install nodejs on my machine. But still the goal was to get a basic Theia product up and running that should be ready to start hacking and customizing it, and then to jump in and create my first Theia extension.

I had started, and aborted again, several attempts to create a Docker container in which I could do that. But so far, I had not managed to create a smooth environment.

Then, recently, I found out about the Docker Dev Environments Preview. This is an experimental feature of Docker Desktop (there seems to be no CLI available for this functionality so far, and also, Docker Desktop is only available for Windows and MacOS). It glues together Git repository cloning, Docker container setup, and VS Code integration. This results in an easy process in which you can get an environment up and running locally with just a few clicks. It seems to be like a small sibling of Gitpod that can be run locally.

So, I have followed the instructions of Composing A Theia Application and have copied the package.json from that page to a new folder on my PC. After playing around a bit with different Docker images, I have come up with this Dockerfile:

FROM node:12

RUN apt-get update \
    && apt-get install -y g++ gcc make python2.7 pkg-config libx11-dev libxkbfile-dev libsecret-1-dev

# install code generator for theia extensions
RUN npm install -g yo generator-theia-extension

USER node


ENTRYPOINT docker-entrypoint.sh

To indicate that Docker Dev Environments shall use the Dockerfile as its container definition, I also had to create a docker-compose.yml file like this:

version: "3.7"
      context: ../docker-container
    stdin_open: true
    tty: true
      - /home/stefan/theia-boilerplate/:/theia:cached
From these three files, I have created the GitHub repository https://github.com/xpomul/theia-boilerplate which can now be used as a template for further Theia experiments.

Getting started is now as simple as following these steps:

  1. Fork the repository on GitHub (or use mine to try it out)
  2. Open Docker Desktop, go to "Dev Environments" and click on "Create Dev Environment". Paste the GitHub URL and Continue. After some time, your Theia Dev Environment should now be up and running.
  3. Click "Open in VS Code". Your workspace should now contain the repository files. From now on, the instructions from https://theia-ide.org/docs/composing_applications can be followed:
  4. Open a new Terminal and enter yarn to download all the Theia dependencies. (That might take quite some time…)
  5. After the process is finished, enter yarn theia build, to build Theia. (Again, this might take some time; and don’t get discouraged by the warning about the filenamify module)
  6. Finally enter yarn theia start --plugins=local-dir:plugins and Theia will come up at http://localhost:3000 (VS Code will announce this and offer to open a browser)

And we are ready to go. From here, we have a running Theia that can be modified and customized by adding and changing files in VS Code and managing Theia in the VS Code Terminal. As a next step, we can, for example, jump into Authoring a Theia Extension.

Have fun!