Configuring Coder's Environment Startup Behavior

This article has been archived. Please see Coder Docs for the updated version.

If you have configuration instructions that apply to everyone who uses an image to create environments, you can define them using the /coder/configure file. For example, you might want all of the image's users to have cloned the project's Git repo.

Coder's environment build process will check the image for its presence; if found, it will execute the instructions contained.

Step 1: Create and define the config file

First, create the configure file containing instructions on what should happen when Coder builds an environment. You can use the text editor of your choice, but you must name the file configure.

For example, the following shows how you can have a Git repo cloned on build:

#!/bin/bash
if [ ! -d "/home/coder/workspace/project" ]
then
  git clone git://company.com/project.git /home/coder/workspace/project
else
  echo "Project has already been cloned."
fi

Please note that the instructions provided include logic on whether the instructions should be re-run (and when) or if the instructions should be run only once. We strongly recommend including this logic at all times to minimize overhead.

Once you've saved your script, you will need to set executable permissions to the configure file. In the terminal, navigate to the folder that contains your file and run chmod 755 configure.

Step 2: Add the config file to the image

Once you have a configure file, you'll need to update your image to use it. You can do so by including the following line in the Dockerfile:

COPY [ "configure", "/coder/configure" ]

For example, let's take a look at the sample Docker file; the final line includes instructions to Coder on copying the settings from the configure file:

FROM ubuntu:latest
RUN apt-get update && apt-get install -y curl
COPY [ "configure", "/coder/configure" ]

Step 3: Build and push the image and config file

To make your image accessible to Coder, build the development image, and push it to the Docker registry. To do so, run the following command in the directory where your Dockerfile is located (be sure to replace the cdr/config placeholder value with your tag and repository name so that the image is pushed to the appropriate location):

To build your image, run:

docker build cdr/config .

Once you've successfully built the image, you can push the image to the Docker registry that you set up with your image building utility.

docker push cdr/config

Step 4: Test the Setup

You can test your setup by:

1. Importing your image
2. Creating an Environment using the newly imported image

If you were successful, Coder will run the configure file during the build process. You can verify this on the Environment Overview page, which shows that Coder runs the configure file as the second-to-last step of the build process: