- Configure Your Project
- Docker Configuration
- Start Tasks
- VS Code Extensions
- Exposing Ports
- Prebuilt Workspaces
- Environment Variables
- Workspace Location
- Editor Configuration
- Gitpod Self-Hosted
- Install on Google Cloud Platform
- Install on Amazon Web Services
- Install on self-managed Kubernetes
- Configure Ingress
- Configure OAuth
- Configure a Database
- Configure a Docker Registry
- Configure Storage
- Configure Nodes
- Configure Workspaces
- Languages & Frameworks
There are two ways to configure a custom Docker image in your
Reference a publicly available image:
The official Gitpod Docker images are hosted on Docker Hub.
Reference a Dockerfile next to your
image: file: .gitpod.Dockerfile
Once committed and pushed, Gitpod will automatically build this Dockerfile when (or before) new workspaces are created.
Note: Currently, Gitpod only supports Debian/Ubuntu or Alpine based images.
A good starting point for creating a custom
.gitpod.Dockerfile is the
gitpod/workspace-full image. It already contains all the tools necessary to work with all languages Gitpod supports.
You can find the source code in this GitHub repository.
FROM gitpod/workspace-full # Install custom tools, runtime, etc. RUN brew install fzf
When you are launching the Gitpod IDE, 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
You can however use
sudo in your Dockerfile. The following example shows a typical
.gitpod.Dockerfile inheriting from
FROM gitpod/workspace-full # Install custom tools, runtime, etc. RUN sudo apt-get update \ && sudo apt-get install -y \ ... \ && sudo rm -rf /var/lib/apt/lists/* # Apply user-specific settings ENV ...
See also Gero’s blog post running through an example.
The easiest way to try out your changes is to push them to a branch and then start another workspace on that branch, keeping the first workspace open as your main editing workspace.
On start of the second workspace the docker build will start and show the output. If your Dockerfile has issues and the build fails or the resulting workspace does not look like you expected, you can force push changes to your config using your first, still running workspace and simply start a fresh workspace again to try them out.
We are working on allowing dockerbuilds directly from within workspaces, but until then this approach has been proven to be the most productive.
Still Have Questions?
Please reach out. We’re happy to answer them.