In a GitHub Codespaces devcontainer.json, when do you use image, build.dockerfile, or dockerComposeFile with service for a front end, API and database?
answer
- pull, build, or orchestrate
- paths relative to the config file
- one service is primary
- Compose keeps its own command
- no host:port forwarding yet
basics
~20 sUse image to start from a ready-made image, build.dockerfile when the repository must extend it, and dockerComposeFile with service when the environment needs several containers, such as a separate database, with the editor attached to one.
solid answer
~50 s`image` pulls an existing image and starts fastest, because nothing is built when the codespace is created. `build.dockerfile` points at a Dockerfile relative to `devcontainer.json`, with `build.context`, `build.args` and `build.target` passed to the build; use it when the team needs packages the image lacks, and use prebuilds because otherwise the build runs at every creation. `dockerComposeFile` (one file or an ordered list, later files overriding earlier ones) plus the required `service` starts several containers and attaches the editor to that service; `runServices` limits which ones start. Features, lifecycle commands and editor customizations apply to that primary container only. With Compose, `overrideCommand` defaults to false, so the service's own command must keep running. As documented in October 2026, Codespaces does not accept the `"host:port"` form of `forwardPorts`, so forward ports the primary container serves and let the app reach the database by its service name.
code
json · 11 lines{
"name": "web-api-db",
"dockerComposeFile": ["../compose.yaml", "compose.dev.yaml"],
"service": "app",
"runServices": ["app", "db"],
"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
"forwardPorts": [3000, 8080],
"features": {
"ghcr.io/devcontainers/features/github-cli:1": {}
}
}go deeper
Recall the three properties that say where the container comes from, and that Compose needs both a file and the name of the service to attach to.
Explain what each choice costs at creation, how paths and build context resolve, and why features and commands reach only the primary Compose service.
Diagnose a Compose container that exits at start or a port that never forwards, and choose between a published image and an in-repository Dockerfile for creation speed.
Decide whether the team's environment should be a centrally published image or repository-owned Dockerfiles, balancing creation time, drift between repositories and who maintains the image.
## Three ways to say where the container comes from A `devcontainer.json` must tell Codespaces how to obtain the container image. The Development Container specification offers three scenarios, and a configuration picks one: | Property | What happens at creation | Best for | |---|---|---| | `image` | The named image is pulled | A team image built elsewhere, or a published dev container image | | `build.dockerfile` | A Dockerfile in the repository is built | Adding system packages or files the base image lacks | | `dockerComposeFile` + `service` | Several containers are started; the editor attaches to one | An app that needs a database or other services beside it | Whichever you choose, **features**, **lifecycle commands** and **customizations** are layered on top of the result, and an organization can restrict which base images are allowed (a policy that sends a non-matching configuration into recovery mode). ## image: reuse a built image `image` is required in this scenario and names an image in a container registry. Nothing is built when the codespace is created; the image is pulled and the container started. That makes it the quickest and most predictable option, and it moves image construction out of the codespace entirely: a pipeline can build and publish the team's image, and every codespace pulls the same image. The cost is that a change to the environment means publishing a new image and updating the tag. Pinning a specific tag rather than a floating one is what makes two codespaces created a week apart identical. ## build: a Dockerfile the repository owns `build.dockerfile` is required in this scenario. Its path, like every path in the file, is **relative to `devcontainer.json`**, not to the repository root. Related settings: - `build.context` sets the directory the build runs from; it defaults to `"."` (the folder holding `devcontainer.json`), and `".."` lets the Dockerfile copy files from the rest of the repository. - `build.args` passes build arguments, and `build.target` selects a stage of a multi-stage Dockerfile. - `build.cacheFrom` names images to use as a build cache. The build runs when a codespace is created, so a slow Dockerfile makes every creation slow. Prebuilds take that cost out of the critical path by building in advance. Writing the Dockerfile itself is a Docker subject; the dev container file only points at it. ## dockerComposeFile: several containers, one primary With Docker Compose, `devcontainer.json` references Compose files rather than replacing them: - `dockerComposeFile` takes one path or an **ordered list**; later files override values from earlier ones, which lets a dev-only file adjust a shared `compose.yaml`. - `service` is **required** and names the container the editor connects to. Features, lifecycle commands and editor settings apply to that **primary** container only. - `runServices` lists which services to start; it defaults to all of them. - `overrideCommand` defaults to **false** for Compose (true for image and Dockerfile), so the primary service runs its own command; if that command exits, the container stops. - `workspaceFolder` sets the folder the editor opens; Codespaces mounts the workspace automatically in Compose scenarios. - `forwardPorts` in Codespaces does not yet accept the `"host:port"` form the specification allows, so an entry naming the database service is not forwarded. Forward the ports the primary container serves, and let the application reach the database over the Compose network by its service name. - `shutdownAction` does not apply to Codespaces, whose lifetime is governed by its own idle timeout. - The separate `mounts` property behaves differently in Codespaces too: bind mounts are ignored, except for the Docker socket, while volume mounts are allowed. ## Choosing for a front end, an API and a database 1. If one container can hold both the front-end dev server and the API, and the database can run as a process or a feature, a single `image` or Dockerfile is simplest and starts fastest. 2. If the database should run as its own container, as it does in production, use Compose: a primary `app` service for the code and editor, a `db` service beside it. 3. Whatever the choice, forward the front end's and the API's ports from the primary container, and enable prebuilds once creation takes more than a couple of minutes. The example configuration on this page shows the Compose shape: two Compose files in order, `app` as the primary service, both services started, and the two web ports forwarded from `app`.
- Why does a Compose-based dev container sometimes stop right after it starts in a codespace?With Compose, `overrideCommand` defaults to false, so the primary service runs its own command instead of the tool's keep-alive loop. If that command exits, the container exits with it. Give the service a long-running command, or set `overrideCommand` to true so the tool keeps the container alive.
- In a Compose setup, which container receives the features and lifecycle commands from devcontainer.json?Only the primary container named by `service`. Features are installed into it, the lifecycle commands run inside it, and the editor attaches to it; other services such as the database run as their Compose definitions say, untouched by the dev container file.
- dockerComposeFile works without naming a service
- Features are installed into every container in the Compose file
- In Codespaces, forwardPorts accepts a service:port entry such as db:9000
- The build.dockerfile path is relative to the repository root
- A Dockerfile configuration builds once and every later codespace reuses it without prebuilds