Skip to content

Commit b26f99e

Browse files
Chuxelbamurtaughsamruddhikhandale
authored
Add article on using Dockerfiles/Compose, formatting tweaks and clarifications (devcontainers#107)
Co-authored-by: Brigit Murtaugh <[email protected]> Co-authored-by: Samruddhi Khandale <[email protected]>
1 parent 966ca8d commit b26f99e

File tree

3 files changed

+163
-15
lines changed

3 files changed

+163
-15
lines changed

‎_posts/2022-11-01-author-a-feature.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ author: "@joshspicer"
55
authorUrl: https://github.com/joshspicer
66
---
77

8-
Development container ['Features'](/features) are self-contained, shareable units of installation code and development container configuration. We [define a pattern](/implementors/features-distribution) for authoring and self-publishing Features.
8+
Development container ["Features"](/features) are self-contained, shareable units of installation code and development container configuration. We [define a pattern](/implementors/features-distribution) for authoring and self-publishing Features.
99

1010
In this document, we'll outline a "quickstart" to help you get up-and-running with creating and sharing your first Feature. You may review an example along with guidance in our [devcontainers/feature-starter](https://github.com/devcontainers/feature-starter) repo as well.
1111

‎_posts/2022-12-16-dockerfiles.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
layout: post
3+
title: "Using Images, Dockerfiles, and Docker Compose"
4+
author: "@chuxel"
5+
authorUrl: https://github.com/chuxel
6+
---
7+
8+
When creating a development container, you have a variety of different ways to customize your environment like ["Features"](/features) or [lifecycle scripts](implementors/json_reference/#lifecycle-scripts). However, if you are familiar with containers, you may want to use a [Dockerfile](#dockerfile) or [Docker Compose / Compose](#docker-compose) to customize your environment. This article will walk through how to use these formats with the Dev Container spec.
9+
10+
## <a href="dockerfile" name="dockerfile" class="anchor"> Using a Dockerfile </a>
11+
12+
To keep things simple, many [Dev Container Templates](/templates) use container image references.
13+
14+
```json
15+
{
16+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu"
17+
}
18+
```
19+
20+
However, [Dockerfiles](https://docs.docker.com/engine/reference/builder/) are a great way to extend images, add additional native OS packages, or make minor edits to the OS image. You can reuse any Dockerfile, but let's walk through how to create one from scratch.
21+
22+
First, add a file named `Dockerfile` next to your `devcontainer.json`. For example:
23+
24+
```Dockerfile
25+
FROM mcr.microsoft.com/devcontainers/base:ubuntu
26+
# Install the xz-utils package
27+
RUN apt-get update && apt-get install -y xz-utils
28+
```
29+
30+
Next, remove the `image` property from `devcontainer.json` (if it exists) and add the `build` and `dockerfile` properties instead:
31+
32+
```json
33+
{
34+
"build": {
35+
// Path is relataive to the devcontainer.json file.
36+
"dockerfile": "Dockerfile"
37+
}
38+
}
39+
```
40+
41+
That's it! When you start up your Dev Container, the Dockerfile will be automatically built with no additional work. See [Dockerfile scenario reference](implementors/json_reference/#image-specific) for more information on other related devcontainer.json properties.
42+
43+
### <a href="dockerfile-image-iteration" name="dockerfile-image-iteration" class="anchor"> Iterating on an image that includes Dev Container metadata </a>
44+
45+
Better yet, you can can use a Dockerfile as a part of authoring an image you can share with others. You can even **add Dev Container settings and metadata right into the image itself**. This avoids having to duplicate config and settings in multiple devcontainer.json files and keeps them in sync with your images!
46+
47+
See the reference on **[pre-building](/implementors/reference/#prebuilding)** to learn more!
48+
49+
## <a href="docker-compose" name="docker-compose" class="anchor"> Using a Dockerfile </a>
50+
51+
[Docker Compose](https://docs.docker.com/compose/) is a great way to define a multi-container development environment. Rather than adding things like databases or redis to your Dockerfile, you can reference existing images for these services and focus your Dev Container's content on tools and utilities you need for development.
52+
53+
### <a href="docker-compose-image" name="docker-compose-image" class="anchor"> Using an image with Docker Compose </a>
54+
55+
As mentioned in the Dockerfile section, to keep things simple, many [Dev Container Templates](/templates) use container image references.
56+
57+
```json
58+
{
59+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu"
60+
}
61+
```
62+
63+
Let's create a `docker-compose.yml` file next to your `devcontainer.json` that references the same image and includes a PostgreSQL database:
64+
65+
```yaml
66+
version: '3.8'
67+
services:
68+
devcontainer:
69+
image: mcr.microsoft.com/devcontainers/base:ubuntu
70+
volumes:
71+
- ../..:/workspaces:cached
72+
network_mode: service:db
73+
command: sleep infinity
74+
75+
db:
76+
image: postgres:latest
77+
restart: unless-stopped
78+
volumes:
79+
- postgres-data:/var/lib/postgresql/data
80+
environment:
81+
POSTGRES_PASSWORD: postgres
82+
POSTGRES_USER: postgres
83+
POSTGRES_DB: postgres
84+
85+
volumes:
86+
postgres-data:
87+
```
88+
89+
In this example:
90+
- `../..:/workspaces:cached` mounts the workspace folder from the local source tree into the Dev Container.
91+
- `network_mode: service:db` puts the Dev Container on the same network as the database, so that it can access it on `localhost`.
92+
- The `db` section uses the [Postgres](https://hub.docker.com/_/postgres) image with a few settings.
93+
94+
Next, let's configure devcontainer.json to use it.
95+
96+
```json
97+
{
98+
"dockerComposeFile": "docker-compose.yml",
99+
"service": "devcontainer",
100+
"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}"
101+
}
102+
```
103+
104+
In this example:
105+
- `service` indicates which service in the `docker-compose.yml` file is the Dev Container.
106+
- `dockerComposeFile` indicates where to find the `docker-compose.yml` file.
107+
- `workspaceFolder` indicates where to mount the workspace folder. This corresponds to a sub-folder under the mount point from `../..:/workspaces:cached` in the `docker-compose.yml` file.
108+
109+
That's it!
110+
111+
### <a href="docker-compose-dockerfile" name="docker-compose-dockerfile" class="anchor"> Using a Dockerfile with Docker Compose </a>
112+
113+
You can also combine these scenarios and use Dockerfile with Docker Compose. This time we'll update `docker-compose.yml` to reference the Dockerfile by replacing `image` with a similar `build` section:
114+
115+
```yaml
116+
version: '3.8'
117+
services:
118+
devcontainer:
119+
build:
120+
context: .
121+
dockerfile: Dockerfile
122+
volumes:
123+
- ../..:/workspaces:cached
124+
network_mode: service:db
125+
126+
db:
127+
image: postgres:latest
128+
restart: unless-stopped
129+
volumes:
130+
- postgres-data:/var/lib/postgresql/data
131+
environment:
132+
POSTGRES_PASSWORD: postgres
133+
POSTGRES_USER: postgres
134+
POSTGRES_DB: postgres
135+
136+
volumes:
137+
postgres-data:
138+
```
139+
140+
Finally, as in the Dockerfile example, you can use this same setup to author a Dev Container image you can share with others and add Dev Container settings and metadata right into the image itself.
141+
142+
See the reference on **[pre-building](/implementors/reference/#prebuilding)** to learn more!

‎supporting.md

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Visual Studio Code specific properties go under `vscode` inside `customizations`
3131
| `settings` | object | Adds default `settings.json` values into a container/machine specific settings file. Defaults to `{}`. |
3232
{: .table .table-bordered .table-responsive}
3333

34-
Please note that [Dev Containers](#dev-containers) and [GitHub Codespaces](#github-codespaces) support the VS Code properties.
34+
Please note that the [Dev Containers](#dev-containers) extension and [GitHub Codespaces](#github-codespaces) support these VS Code properties.
3535

3636
### <a href="#visual-studio" name="visual-studio" class="anchor"> Visual Studio </a>
3737

@@ -41,30 +41,36 @@ You may learn more in the [announcement blog post](https://devblogs.microsoft.co
4141

4242
## <a href="#tools" name="tools" class="anchor"> Tools </a>
4343

44-
## <a href="#devcontainer-cli" name="devcontainer-cli" class="anchor"> Dev Container CLI </a>
44+
### <a href="#devcontainer-cli" name="devcontainer-cli" class="anchor"> Dev Container CLI </a>
4545

46-
A dev container command line interface (CLI) that implements this specification. It is in development in the [devcontainers/cli](https://github.com/devcontainers/cli) repo.
46+
The dev container command line interface (CLI) is a reference implementation for the Dev Container spec. It is in development in the [devcontainers/cli](https://github.com/devcontainers/cli) repo. It is intended both for use directly and by tools or services that want to support the spec.
4747

48-
The CLI can take a `devcontainer.json` and create and configure a dev container from it. It allows for prebuilding dev container definitions using a CI or DevOps product like GitHub Actions. It can detect and include dev container features and apply them at container runtime, and run [lifecycle commands](implementors/json_reference/#lifecycle-scripts) like `postCreateCommand`, providing more power than a plain `docker build` and `docker run`.
4948

50-
### <a href="#dev-containers-cli" name="dev-containers-cli" class="anchor"> VS Code extension CLI </a>
49+
The CLI can take a `devcontainer.json` and create and configure a dev container from it. It allows for prebuilding dev container definitions using a CI or DevOps product like GitHub Actions. It can detect and include dev container features and apply them at container runtime, and run [lifecycle scripts](implementors/json_reference/#lifecycle-scripts) like `postCreateCommand`, providing more power than a plain `docker build` and `docker run`.
5150

52-
VS Code has a [CLI](https://code.visualstudio.com/docs/remote/devcontainer-cli) which may be installed within the Dev Containers extension or through the command line.
51+
#### <a href="#dev-containers-cli" name="dev-containers-cli" class="anchor"> VS Code extension CLI </a>
52+
53+
The [VS Code Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) includes a variation of the devcontainer CLI that adds the ability use the command line to open the a Dev Container in VS Code. It is also automatically updated when the extension updates.
54+
55+
Press <kbd>cmd/ctrl</kbd>+<kbd>shift</kbd>+<kbd>p</kbd> or <kbd>F1</kbd> and select the **Dev Containers: Install devcontainer CLI** command to install it.
5356

5457
### <a href="#cachix-devenv" name="cachix-devenv" class="anchor"> Cachix devenv </a>
5558

56-
Cachix's [devenv](https://devenv.sh/) supports automatically generating a `.devcontainer.json` file so you can use it with any Dev Container spec supporting tool. See [devenv documentation](https://devenv.sh/integrations/codespaces-devcontainer/) for detais.
59+
Cachix's **[devenv](https://devenv.sh/)** now supports automatically generating a `.devcontainer.json` file. This gives you a more convenient and consistent way to use [Nix](https://nixos.org/) with any Dev Container spec supporting tool or service!
60+
61+
See [devenv documentation](https://devenv.sh/integrations/codespaces-devcontainer/) for detais.
5762

5863
### <a href="#jetpack-io-devbox" name="jetpack-io-devbox" class="anchor"> Jetpack.io Devbox </a>
5964

60-
[Jetpack.io's VS Code extension](https://marketplace.visualstudio.com/items?itemName=jetpack-io.devbox) supports a **Generate Dev Container files** command so you can use Jetpack.io from Dev Container spec supporting tools.
65+
[Jetpack.io](https://jetpack.io) is a [Nix](https://nixos.org/)-based service for deploying applications. [DevBox](https://www.jetpack.io/devbox/) provides a way to use Nix to generate a development environment. [Jetpack.io's VS Code extension](https://marketplace.visualstudio.com/items?itemName=jetpack-io.devbox) allows you to quickly take advantage of DevBox in any Dev Container spec supporting tool or service.
6166

67+
Press <kbd>cmd/ctrl</kbd>+<kbd>shift</kbd>+<kbd>p</kbd> or <kbd>F1</kbd> and select the **Generate Dev Container files** command to get started!
6268

63-
### <a href="#dev-containers" name="dev-containers" class="anchor"> Visual Studio Code Dev Containers </a>
69+
### <a href="#dev-containers" name="dev-containers" class="anchor"> VS Code Dev Containers extension </a>
6470

65-
The [**Visual Studio Code Dev Containers** extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets you use a [Docker container](https://docker.com) as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. There is more information in the Dev Containers [documentation](https://code.visualstudio.com/docs/remote/containers).
71+
The [Visual Studio Code Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets you use a [Docker container](https://docker.com) as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. There is more information in the Dev Containers [documentation](https://code.visualstudio.com/docs/remote/containers).
6672

67-
> **Tip:** If you make a change to your dev container after having built and connected to it, be sure to run **Dev Containers: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make.
73+
> **Tip:** If you make a change to your dev container after having built and connected to it, be sure to run **Dev Containers: Rebuild Container** from the Command Palette (<kbd>cmd/ctrl</kbd>+<kbd>shift</kbd>+<kbd>p</kbd> or <kbd>F1</kbd>) to pick up any changes you make.
6874
6975
#### <a href="#product-specific-properties" name="product-specific-properties" class="anchor"> Product specific properties </a>
7076

@@ -82,13 +88,13 @@ Some properties may also have certain limitations in the Dev Containers extensio
8288
| `${localWorkspaceFolderBasename}` | Any | Not yet supported when using Clone Repository in Container Volume. |
8389
{: .table .table-bordered .table-responsive}
8490

91+
## <a href="#services" name="services" class="anchor"> Services </a>
92+
8593
### <a href="#github-codespaces" name="github-codespaces" class="anchor"> GitHub Codespaces </a>
8694

8795
A [codespace](https://docs.github.com/en/codespaces/overview) is a development environment that's hosted in the cloud. Codespaces run on a variety of VM-based compute options hosted by GitHub.com, which you can configure from 2 core machines up to 32 core machines. You can connect to your codespaces from the browser or locally using Visual Studio Code.
8896

89-
> **Tip:** If you make a change to your dev container after having built and connected to your codespace, be sure to run **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make.
90-
91-
> **Tip** Codespaces implements an auto `workspaceFolder` mount in **Docker Compose** scenarios.
97+
> **Tip:** If you make a change to your dev container after having built and connected to your codespace, be sure to run **Codespaces: Rebuild Container** from the Command Palette (<kbd>cmd/ctrl</kbd>+<kbd>shift</kbd>+<kbd>p</kbd> or <kbd>F1</kbd>) to pick up any changes you make.
9298
9399
#### <a href="#codespaces-specific-properties" name="codespaces-specific-properties" class="anchor"> Product specific properties </a>
94100
GitHub Codespaces works with a growing number of tools and, where applicable, their `devcontainer.json` properties. For example, connecting the Codespaces web editor or VS Code enables the use of [VS Code properties](#visual-studio-code).

0 commit comments

Comments
 (0)