Devcontainer Examples

This repository contains simple devcontainer examples that can be used as starting points for project-specific development environments. It's also a great way to start learning something new that you don't want to setup locally, or even when starting a new project and deciding on the dev-experience part of the ways of working of the team.

Devcontainers are containerized development environments. You can think of them as packaged workspaces that open with the tools and settings needed for development. For AI projects, it adds another important benefit: You can let the AI roam free inside the devcontainer without worrying about your files, as long as you don't let it force push into your main branch, whatever damage they do should not impact you directly.

Devcontainers are useful when project tooling is complex or when a team wants a repeatable onboarding path. This is very useful, even in non-AI projects. A developer usually needs a containerization tool and an IDE or editor that supports devcontainers. Docker and Visual Studio Code are common choices, but other compatible tools can also be used.

Creating a specialized devcontainer for a project can take time, depending on team and project needs. A basic devcontainer can usually be set up quickly and then improved as requirements become clearer.

Pro-tip: Clone this repository, open it with your IDE and ask your AI of choice to help you prepare a devcontainer based on the examples and know-how notes for your particular project.

See CONTENTS.md for the current example list, other/ for practical know-how notes, and CONTRIBUTING.md for guidance on adding new examples.

Using An Example

To add one of these devcontainer setups to a new or existing repository:

1. Choose the example folder that is closest to your project needs.
2. Create a .devcontainer/ folder at the root of your target repository.
3. Copy the files from the chosen example folder into .devcontainer/.
4. Review devcontainer.json and adjust names, paths, ports, features, extensions, environment variables, and post-create commands for the target project.
5. If the example includes a Dockerfile or docker-compose.yml, check that all referenced file paths are still correct after copying.
6. Open the target repository with a devcontainer-compatible tool and rebuild the container.

For a new repository, create the project files first or copy the devcontainer setup first. Both approaches work as long as devcontainer.json ends up inside .devcontainer/ at the repository root.

For an existing repository, add .devcontainer/ alongside the existing project files. Keep project-specific source code, tests, and documentation in their normal locations unless the selected devcontainer example explicitly requires another layout.

Adapting An Example

After copying an example, treat it as project configuration:

• Remove tools and settings that the project does not need.
• Add project-specific setup commands only when they are repeatable for the team.
• Prefer clear comments for non-obvious setup choices.
• Keep secrets out of devcontainer files. Use the secret or environment handling supported by your tooling.
• Document any required host tools, such as Docker, compatible editors, or private registry access.

Remember that modifiying the devcontainer files requires that you rebuild the container. Using VS Code on OSX you can execute the rebuild at any point by opening the command palette (Command + Shift + P) and then finding and executing "Dev Containers: Rebuild Container".

Also keep in mind that if you are working on a team setting, your team members will also have to rebuild their containers in their machines to see the changes.

Ports

None of the examples define ports by default. In devcontainer.json, forwardPorts is usually the preferred setting for development use: it forwards one or more ports from inside the container to the local machine, including services that a devcontainer-compatible tool may not auto-detect.

appPort is also available, but it publishes ports more like Docker port publishing. For most cases, prefer forwardPorts; use appPort only when publishing is specifically needed.

The examples leave both settings unset because the correct ports depend on the project being placed inside the container. We cannot foresee every use case, so add forwardPorts, appPort, or other port forwarding settings after copying an example into a real project.