Bring your own (Docker) image to Gitpod

Since we released Gitpod into Public Beta it has been incredibly exciting to see people from all over the world use our service. Even more so with feedback like this:

Of course, there is always room for improvement, especially with a service as new as Gitpod. Luckily, people have started to share their questions and ideas with us on One of the most often asked questions was:

“How do I add tool XYZ to my workspace?”

And indeed that hasn’t been straight forward. You had to:

  • create a Dockerfile on your machine
  • build that Dockerfile on your machine
  • push it to (no account? Create one first!)
  • create a branch in your project with a customized .gitpod.yml file which references that specific image
  • visit<your-repos-branch-url>
  • get no feedback except ‘Build has status FAILURE’…
  • rinse and repeat from step 2

That was way too tedious for everyone to start playing around.

Let Gitpod do the heavy lifting

To improve this experience we introduced Dockerfile support (#62), which lets you reference your Dockerfile directly from inside your .gitpod.yml file:

file: docker/Dockerfile

Now, Gitpod knows about the Dockerfile and builds that image for you. Whenever you access the repository on Gitpod it checks whether the Dockerfile has been updated and rebuilds the image if needed. When this happens you’ll be shown the log output of the build for easier debugging, too.

An example, please!

Let’s get concrete. As an exercise we’ll use a minimal REST service written in Rust using Rocket and Diesel that talks to a PostgreSQL DB. It also has a nice blog post to get started.

The example relies on a very specific nightly build of the Rust compiler from May 2018. Thus, a simple won’t get you up-and-running. Of course, you could switch Rust toolchains but then other projects on your machine might stop working. Furthermore, there is more setup and tools to install: A database, a CLI tool…
Gitpod to the rescue!

I went to gitpod-io/definitely-gp and added a .gitpod.yml and Dockerfile there. The .gitpod.yml file looks like this:

It references the Dockerfile next to it, says that the resulting app should be accessible on port 8000 and contains the command executed on workspace startup: set config, start postgres, build and run app (I basically copied those from the repo’s file).

The Dockerfile itself inherits from our default image gitpod/workspace-full¹ and contains:

  • PostgreSQL (+ some configuration for the gitpod user)
  • specific Rust toolchain
  • some project specific setup

Here it is:

Remember, this is done once per project. Most projects already have those setup descriptions, they are just buried inside their README.

Now whenever anyone accesses the repository through Gitpod, be it a branch, a particular commit, an issue or a PR, they will get a custom workspace with all the tools set up and running, out of the box. Give it a spin!

Once the service has build and is running, we just follow the tutorial:

  • Open : Click on the appearing messagebox² and change the path in the integrated browser to , click : The query results in an empty
  • Hit and paste:
curl -XPOST http://localhost:8000/people -H "Content-Type: application/json" --data '{"id": 123, "first_name": "Jon", "last_name": "Doe", "age": 64, "profession": "Engineer", "salary": 1024}'
  • Hit again to see Jon Doe’s entry

Try it yourself

You can either create a PR on gitpod-io/definitely-gp — or dive right in and create the .gitpod.yml in your repositories! For details on how this works and what is possible please head over to the docs.

¹ It is not required to inherit from that image at all. You can even start with a plain alpine or debian based image. I used it here for convenience.

² Alternatively, go to and click


Gitpod - Online IDE for GitHub

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store