Workspace Image
Learn how to use different workspaces images available in Gitpod. The workspace image defines the base environment from which your workspaces are created. Or, you can create and use your own custom workspace images.
By default, Gitpod uses a standard Docker Image called Workspace-Full
as the foundation for workspaces. Workspaces started based on this default image come pre-installed with Docker, Nix, Go, Java, Node.js, C/C++, Python, Ruby, Rust, Clojure as well as tools such as Homebrew, Tailscale, Nginx and several more.
If this image does not include the tools you need for your project, you can provide a public Docker image or your own Dockerfile. This provides you with the flexibility to install the tools & libraries required for your project.
Gitpod supports Debian/Ubuntu based Docker images out-of-the-box. Some base images like Alpine do not include libgcc and libstdc++ by default, which breaks Visual Studio Code. See a reference Alpine base image and issue #3356.
Configuring a Workspace Image
Use a public Docker image
You can define a public Docker image in your .gitpod.yml
file with the following configuration:
The official Gitpod Docker images are hosted on Docker Hub.
You can find the source code for these images in this GitHub repository.
Docker image tags
For public images, feel free to specify a tag, e.g. image: node:buster
if you are interested in a particular version of the Docker image.
For Gitpod images, we recommend using timestamped tag for maximum reproducibility, for example image: gitpod/workspace-full:2022-05-08-14-31-53
(taken from the Tags
panel on this dockerhub page for example)
Use a private Docker image
If you are using Gitpod Enterprise as well as a Private ECR registry to store images, it is recommended to leverage Gitpod Enterprise’s built-in functionality to authenticate with private ECR registries instead of the method described here.
The video above uses dockerhub as the reference, if you’re using Google Artifact Registry then see this video afterwards.
Gitpod supports private Docker images that require a username and password. You can provide these registry credentials to Gitpod by setting the GITPOD_IMAGE_AUTH
environment variable to <registry-domain>:<base64-encoded 'username:password'>
. Like all other environment variables, it can be configured on different levels. In addition, there is a special Organization-wide setting, which allows to provide authentication in a central place.
For example, if the registry is docker.io
, the username is foo
and the password is bar
, the GITPOD_IMAGE_AUTH
environment variable value may be calculated using the command echo -n "docker.io:"; echo -n "foo:bar" | base64 -w0
which outputs docker.io:Zm9vOmJhcg==
. Credentials for different hosts can be appended, separated by a ,
.
The image can then be referenced as follows in the .gitpod.yml
:
By default, the environment variable GITPOD_IMAGE_AUTH
is not mounted into workspace for security reasons. If this is wanted nontheless (e.g. to enable developers to seemlessly use docker pull
/ docker push
, or to enable the gp validate
workflow), there is an option to authenticate dockerd
in the Repository configuration.
Using a custom Dockerfile
This option provides you with the most flexibility. Start by adding the following configuration in your .gitpod.yml
file:
Next, create a .gitpod.Dockerfile
file at the root of your project. The syntax is the regular Dockerfile
syntax as documented on docs.docker.com.
A good starting point for creating a custom .gitpod.Dockerfile
is the gitpod/workspace-full image as it already contains all the tools necessary to work with all languages
Gitpod supports.
Caveat: COPY
instructions in a Dockerfile is only evaluated once and then
cached.
See this to break the cache and trigger a rebuild.
Docker support: If you use the gitpod/workspace-full
image, you get Docker support built-in to your environment.
If you want a base image without the default tooling installed then use the gitpod/workspace-base image.
When you launch a Gitpod workspace, the local console will use the gitpod
user, so all local settings, config file, etc. should apply to /home/gitpod
or be run using USER gitpod
(we no longer recommend using USER root
).
You can however use sudo
in your Dockerfile. The following example shows a typical .gitpod.Dockerfile
inheriting from gitpod/workspace-full
:
Once committed and pushed, Gitpod will automatically build this Dockerfile when (or before) new workspaces are created.
See also Gero’s blog post running through an example.
What is available at build time
Available:
-
Git repository at CWD.
Note: additionalRepositories from the multi-repos feature will not be available in this context.
For example, you can copy your repository inside the image and execute a script:
Not available:
-
Gitpod environment variables, not available due to security reasons.
If you want to access Gitpod environment variables when building images using the Docker daemon running in your workspace. Here’s what you could do:
- Prepare a custom dockerfile (
.gitpod.Dockerfile
), example contents:
- Build an image using the Docker daemon running in your workspace like so:
docker build --build-arg DOWNLOAD_URL -f .gitpod.Dockerfile .
- Push the image to your dockerhub account and change it’s visibility to private.
- Use the image from your
.gitpod.yml
:
- Setup private docker image support on Gitpod to use it.
- Prepare a custom dockerfile (
Custom base image
While it is recommended to extend one of the Gitpod-provided base images for custom Dockerfiles to ensure the image has the required dependencies for a workspace, it is possible to configure a Dockerfile with a public (Debian/Ubuntu-based) image as its base.
There are some requirements for a public base image to work properly as a workspace. For example, you’ll need to set up the gitpod
user with the right UID, and install git
to ensure your workspace can start. See the below Dockerfiles as a reference.
Ubuntu
Alpine
Additional tools & languages: see https://github.com/gitpod-io/workspace-images/tree/main/chunks for references to configure your workspace image with common tools and languages. For instance, this Dockerfile shows how to install docker
and docker-compose
.
Tailscale: see the Tailscale integration docs for setting up Tailscale in a custom Dockerfile.
Validate and apply a workspace image
To validate your workspace image is working execute the gp validate
command from within the workspace with your configuration changes. For the configuration change to apply for all new workspaces you must commit and push your configuration to source control.
For a full guide, see Configuring Workspaces.
Manually rebuild a workspace image
Sometimes you find yourself in situations where you want to manually rebuild a workspace image, for example if packages you rely on released a security fix.
You can trigger a workspace image rebuild with the following URL pattern: https://gitpod.io/#imagebuild/<your-repo-url>
.
Configure a custom shell
Feedback needed: Custom shell support is in the works. The below shows a method for running some of the
~/.bashrc.d
startup scripts. To leave feedback on the approach, please see this GitHub issue: #10105.
For example, if you wish to default your workspace-image to zsh
, you could do it from your custom dockerfile with the following line:
Tip: You could also create an environment variable at https://gitpod.io/variables called SHELL
with */*
scope for setting a personal default SHELL.
Caveat: Shells like fish
, zsh
and etc. are not POSIX-compliant or bash-compatible, so your Gitpod tasks might error if you use some POSIX or bash specific features in your task scripts.
Load bash environment in custom shell
Currently we put some startup scripts for the workspace-images at ~/.bashrc.d
, that means if you change your SHELL from bash
to something else, they will not auto run. You could run the following command from your SHELL to workaround:
Define Dynamic Global Environment Variables from Dockerfile
Certain resources or contexts available during a running Gitpod workspace are not present within the Docker build environment. If you need to set environment variables that depend on the running workspace and need to be accessible by the editor (e.g., VS Code, JetBrains IDEs) as well as all terminals, you can use the following strategy. This approach should work on Docker images based on most modern Linux distributions.
In your Dockerfile, you can add something like below:
Bash reads /etc/bash.bashrc
before ~/.bashrc
for interactive non-login shells, so this configuration is usually applied system-wide from one of the initialization processes.
You can read more about this here.
FAQs
Why is my custom dockerfile rebuilding everytime even with no change made to it?
This usually happens when you don’t pin the image tag (AKA version) inside your custom dockerfile.
In such cases, it could be that there has been long gaps between the time you reuse a workspace or create a new one. We usually release new images every week so if there was more than one week between each start then the image will be rebuild every time.
So, for example, if your .gitpod.Dockerfile
looks like the following:
You could grab a timestamped tag from here for gitpod/workspace-full
.
And then your .gitpod.Dockerfile
could look like:
Note: Please grab a recent tag from the linked page, don’t copy paste the example from here.
Also see docker-image-tags for more info.
How to run a Desktop app for GUI development inside a Gitpod workspace
If you wish to do GUI application development in Gitpod and getting errors such as:
- Unable to init server: Could not connect : Connection refused
- No display server running
- Xorg missing
xdg-open
command not found
Then you need to use the gitpod/workspace-full-vnc
docker image. See this page for more info.
Was this page helpful?