Skip to main content

You've found one of our experimental articles! Have ideas or feedback for how we can further improve this article? Let us know in the discussion.

Add a dev container configuration to your repository

This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your Java codebase. For more information, see "Introduction to dev containers."

If you want to add a dev container configuration for another programming language, click the language button to the right.

Prerequisites

Step 1: Open your project in a codespace

  1. Under the repository name, use the Code drop-down menu, and in the Codespaces tab, click Create codespace on BRANCH.

    New codespace button

    If you don’t see this option, GitHub Codespaces isn't available for your project. See Access to GitHub Codespaces for more information.

When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Java, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.

GitHub Codespaces uses a file called devcontainer.json to configure the development container that you use when you work in a codespace. Each repository can contain one or more devcontainer.json files, to give you exactly the development environment you need to work on your code in a codespace.

On launch, GitHub Codespaces uses a devcontainer.json file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "Introduction to dev containers."

Step 2: Add a dev container configuration to your repository from a template

The default development container, or "dev container," for GitHub Codespaces comes with the latest Java version, package managers (Maven, Gradle), and other common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.

To set up your repository to use a custom dev container, you will need to create one or more devcontainer.json files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "Introduction to dev containers".

  1. Access the Command Palette (Shift + Command + P / Ctrl + Shift + P), then start typing "dev container". Select Codespaces: Add Development Container Configuration Files.... "Codespaces: Add Development Container Configuration Files..." in the command palette
  2. For this example, click Java. In practice, you could select any container that’s specific to Java or a combination of tools such as Java and Azure Functions. Select Java option from the list
  3. Click the recommended version of Java. Java version selection
  4. Select any additional features to install and click OK.
  5. Access the command palette (Shift + Command + P/ Ctrl + Shift + P), then start typing "rebuild". Select Codespaces: Rebuild Container. Rebuild container option

Anatomy of your dev container

Adding the Java dev container template adds a .devcontainer directory to the root of your project's repository with the following files:

  • devcontainer.json
  • Dockerfile

The newly added devcontainer.json file defines a few properties that are described below.

name - You can name your dev container anything, this is just the default.

build - The build properties.

  • dockerfile - In the build object, dockerfile contains the path to the Dockerfile that was also added from the template.
  • args
    • VARIANT: This file only contains one build argument, which is the Java version that is passed into the Dockerfile.

settings - These are Visual Studio Code settings that you can set.

  • terminal.integrated.shell.linux - While bash is the default here, you could use other terminal shells by modifying this.

extensions - These are extensions included by default.

  • vscjava.vscode-java-pack - The Java Extension Pack provides popular extensions for Java development to get you started.

forwardPorts - Any ports listed here will be forwarded automatically.

postCreateCommand - Use this to run commands that aren't defined in the Dockerfile, after your codespace is created.

remoteUser - By default, you’re running as the vscode user, but you can optionally set this to root.

Dockerfile

You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.

Step 3: Modify your devcontainer.json file

With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.

  1. In the Explorer, expand the .devcontainer folder and select the devcontainer.json file from the tree to open it.

    devcontainer.json file in the Explorer

  2. Add the following lines to your devcontainer.json file after extensions.

    "postCreateCommand": "java -version", "forwardPorts": [4000],

    For more information about devcontainer.json properties, see the Visual Studio Code documentation: "devcontainer.json reference."

  3. Access the command palette (Shift + Command + P/ Ctrl + Shift + P), then start typing "rebuild". Select Codespaces: Rebuild Container. Rebuild container option Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.

Step 4: Run your application

In the previous section, you used the postCreateCommand to install a set of packages via npm. You can now use this to run our application with npm.

  1. Run your application by pressing F5.

  2. When your project starts, you should see a message in the bottom right corner with a prompt to connect to the port your project uses. Port forwarding toast

Step 5: Commit your changes

Once you've made changes to your codespace, either new code or configuration changes, you'll want to commit your changes. Committing changes to your repository ensures that anyone else who creates a codespace from this repository has the same configuration. This also means that any customization you do, such as adding Visual Studio Code extensions, will appear for all users.

For information, see "Using source control in your codespace."

bouncing octocatLoading...