123.9K
Skip to main content
HomeAdministrationTemplatesManaging TemplatesImage Management

Image Management

While Coder provides example container images for workspaces, it's often best to create custom images that match the needs of your users. This document serves as a guide to operational maturity with some best practices around managing workspace images for Coder.

After following this tutorial, you'll accomplish the following:

  1. Create a minimal base image.
  2. Create golden images with standard tooling.
  3. Create project-specific images for common use cases.
  4. Let developers customize their own environment.

An image is just one of the many properties defined within the template. Templates can pull images from a public image registry (e.g. Docker Hub) or an internal one, thanks to Terraform. Each image reference below can be dropped directly into a template's image variable or parameter.

Create a minimal base image

While you may not use this directly in Coder templates, it's useful to have a minimal base image as a small image that contains only the necessary dependencies to work in your network and work with Coder. Here are some things to consider:

  • curl, wget, or busybox is required to download and run the agent
  • git is recommended so developers can clone repositories
  • If the Coder server is using a certificate from an internal certificate authority (CA), you'll need to add or mount these into your image
  • Other generic utilities that will be required by all users, such as ssh, docker, bash, jq, and/or internal tooling
  • Consider creating (and starting the container with) a non-root user

Examples:

Create golden images with standard tooling

Building on the base image, it's often practical to have a few golden images that contain standard tooling for developers. These images should contain a number of languages (e.g. Python, Java, TypeScript), IDEs (VS Code, JetBrains, PyCharm), and other tools (e.g. docker). Unlike project-specific images (which are also important), general purpose images are great for:

  • Scripting: Developers may just want to hop in a Coder workspace to run basic scripts or queries.
  • Day 1 Onboarding: New developers can quickly get started with a familiar environment without having to browse through (or create) an image
  • Basic Projects: Developers can use these images for simple projects that don't require any specific tooling outside of the standard libraries. As the project gets more complex, its best to move to a project-specific image.
  • "Golden Path" Projects: If your developer platform offers specific tech stacks and types of projects, the golden image can be a good starting point for those projects.

This is often referred to as a "sandbox" or "kitchen sink" image. Since large multi-purpose container images can quickly become difficult to maintain, it's important to keep the number of general-purpose images to a minimum (2-3 in most cases) with a well-defined scope.

Examples:

Create project-specific images for common use cases

Beyond golden images, create images scoped to a specific project, language, or use case (e.g., a Go backend, a Node.js frontend, or a data science stack). These images stay smaller and faster to pull than one larger image that tries to install all dependencies.

Examples:

Let developers customize their own environment

Even with well-scoped images, developers will often need tooling that is specific to their project or personal workflow. Instead of maintaining an image for every combination, developers can layer their own customizations on top of a smaller image: