devcontainer.json
Devsy uses the open devcontainer.json standard to define a project's development container. VS Code and GitHub Codespaces use the same format, so existing configurations work in Devsy.
If a project has no configuration, Devsy detects the language and uses a default.
For the full format, see the reference, the VS Code documentation, and the Codespaces documentation.
Where the file lives
Devsy looks for one of:
.devcontainer/devcontainer.json.devcontainer.json.devcontainer/<folder>/devcontainer.json
To use a specific file, pass its path:
devsy workspace up github.com/my-org/my-repo --devcontainer ./path/to/devcontainer.jsonUse extends to inherit from other files. It takes a path or a list of paths. Keep the files a configuration depends on inside its folder.
Existing workspaces
Devsy remembers which configuration each workspace uses. If a later search finds a different file, Devsy warns and keeps the saved one. To switch files, recreate the workspace:
devsy workspace up <workspace> --recreate --devcontainer "<relative-path>"
devsy workspace up <workspace> --recreate --devcontainer "id:<name>"Devsy saves the choice for later runs.
Dockerfile
{
"build": {
"dockerfile": "Dockerfile"
}
}Docker Compose
Set dockerComposeFile to one or more Compose files. Set service to the service that runs as the dev container:
{
"dockerComposeFile": ["docker-compose.yml", "docker-compose.dev.yml"],
"service": "backend"
}Devsy names the Compose project the same way Docker Compose does, so it reuses a project that is already running. It checks these sources in order:
COMPOSE_PROJECT_NAMEin your shell.COMPOSE_PROJECT_NAMEin an.envfile, in the devcontainer folder, the workspace root, or a compose file's folder.- The top-level
name:in the compose files. The last file that sets it wins. - A name derived from the workspace.
The name field in devcontainer.json is only a display name and never names the compose project.
A custom DOCKER_HOST set for the Docker provider is passed to the docker compose commands Devsy runs.
Features
Features are reusable pieces that Devsy merges into your Dockerfile, such as docker-in-docker or kubectl.
To send HTTP headers when Devsy downloads a feature archive, set them under customizations:
{
"features": {
"https://example.com/foo_feature.tar.gz": {}
},
"customizations": {
"devsy": {
"featureDownloadHTTPHeaders": {
"FOO_HEADER": "${localEnv:FOO_ENV_VAR}",
"BAR_HEADER": "bar"
}
}
}
}Applying changes
After you edit the configuration, apply it without deleting the workspace:
devsy workspace up my-workspace --recreateDevsy builds and validates the new image before stopping or replacing the existing container. If the build fails, the existing workspace stays in its previous state, whether running or stopped. A later failure can leave the old container stopped or removed, depending on the provider. Pass --recovery to start a recovery container with features and lifecycle commands disabled if the build fails.
Recreating
Anything outside volumes is lost. The project folder and other mounted paths stay.
Environment variables in devcontainer.json
With the SSH provider, the variable in ${localEnv:NAME} must reach the remote machine.
-
Reference the variable in
devcontainer.json:{ "name": "Node.js", "image": "mcr.microsoft.com/devcontainers/javascript-node:${localEnv:IMAGE_VERSION}" } -
Send it from your local
~/.ssh/config:Host <REMOTE-SSH-SERVER> SetEnv IMAGE_VERSION=0-18-bullseye -
On the remote machine, add
AcceptEnv IMAGE_VERSIONto/etc/ssh/sshd_configand restart the SSH service. -
Start the workspace:
devsy workspace up <GITHUB-REPOSITORY-URL> --provider ssh --ide=none