Skip to content

Commit 9974ef4

Browse files
samruddhikhandalesamruddhikhandale
authored
Merge pull request #98 from devcontainers/samruddhikhandale/templates-proposal
Dev container Templates & distribution
2 parents 85506cf + 44c75b8 commit 9974ef4

File tree

2 files changed

+311
-0
lines changed

2 files changed

+311
-0
lines changed

‎proposals/devcontainer-templates-distribution.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Distribution and Discovery of Dev Container Templates
2+
3+
This specification defines a pattern where community members and organizations can author and self-publish [Dev Container Templates](./devcontainer-templates.md).
4+
5+
Goals include:
6+
7+
- For Template authors, create a "self-service" way to publish a Template, either publicly or privately, that is not centrally controlled.
8+
- Provide the ability to standardize publishing such that supporting tools may implement their own mechanism to aid Template discoverability as they see fit.
9+
10+
## Source code
11+
12+
A Template's source code is stored in a git repository.
13+
14+
For ease of authorship and maintenance, [1..n] Templates can share a single git repository. This set of Templates is referred to as a "collection," and will share the same [`devcontainer-collection.json`](#devcontainer-collection.json) file and "namespace" (eg. `<owner>/<repo>`).
15+
16+
> **Note:** Templates and [Features](./devcontainer-features.md) should be placed in different git repositories.
17+
18+
Source code for a set of Templates follows the example file structure below:
19+
20+
```
21+
.
22+
├── README.md
23+
├── src
24+
│ ├── dotnet
25+
│ │ ├── devcontainer-template.json
26+
│ │ ├── .devcontainer.json
27+
│ │ ├── ...
28+
| ├
29+
│ ├── docker-from-docker
30+
│ │ ├── devcontainer-template.json
31+
│ │ ├── .devcontainer
32+
│ │ ├── devcontainer.json
33+
│ │ ├── Dockerfile
34+
│ │ └── ...
35+
│ │ ├── ...
36+
| ├
37+
│ ├── go-postgres
38+
│ │ ├── devcontainer-template.json
39+
│ │ ├── .devcontainer
40+
│ │ ├── devcontainer.json
41+
│ │ ├── docker-compose.yml
42+
│ │ ├── Dockerfile
43+
│ │ └── ...
44+
│ │ ├── ...
45+
```
46+
47+
...where `src` is a directory containing a sub-folder with the name of the Template (e.g. `src/dotnet` or `src/docker-from-docker`) with at least a file named `devcontainer-template.json` that contains the Template metadata, and a `.devcontainer.json` (or `.devcontainer/devcontainer.json`) that the supporting tools will drop into an existing project or folder.
48+
49+
Each sub-directory should be named such that it matches the `id` field of the `devcontainer-template.json`. Other files can also be included in the Templates's sub-directory, and will be included during the [packaging step](#packaging) alongside the two required files. Any files that are not part of the Templates's sub-directory (e.g. outside of `src/dotnet`) will not included in the [packaging step](#packaging).
50+
51+
## Versioning
52+
53+
Each Template is individually [versioned according to the semver specification](https://semver.org/). The `version` property in the respective `devcontainer-template.json` file is parsed to determine if the Template should be republished.
54+
55+
Tooling that handles publishing Templates will not republish Templates if that exact version has already been published; however, tooling must republish major and minor versions in accordance with the semver specification.
56+
57+
## Packaging
58+
59+
Templates are distributed as tarballs. The tarball contains the entire contents of the Template sub-directory, including the `devcontainer-template.json`, `.devcontainer.json` (or `.devcontainer/devcontainer.json`), and any other files in the directory.
60+
61+
The tarball is named `devcontainer-template-<id>.tgz`, where `<id>` is the Templates's `id` field.
62+
63+
A reference implementation for packaging and distributing Templates is provided as a GitHub Action (https://github.com/devcontainers/action).
64+
65+
### devcontainer-collection.json
66+
67+
The `devcontainer-collection.json` is an auto-generated metadata file.
68+
69+
| Property | Type | Description |
70+
| :--- | :--- | :--- |
71+
| `sourceInformation` | object | Metadata from the implementing packaging tool. |
72+
| `templates` | array | The list of Templates that are contained in this collection.|
73+
74+
Each Template's `devcontainer-template.json` metadata file is appended into the `templates` top-level array.
75+
76+
## Distribution
77+
78+
There are several supported ways to distribute Templates. Distribution is handled by the implementing packaging tool.
79+
80+
A user can add a Template in to their projects as defined by the [supporting Tools](../docs/specs/supporting-tools.md#supporting-tools-and-services).
81+
82+
### OCI Registry
83+
84+
An OCI registry that implements the [OCI Artifact Distribution Specification](https://github.com/opencontainers/distribution-spec) serves as the primary distribution mechanism for Templates.
85+
86+
Each packaged Template is pushed to the registry following the naming convention `<registry>/<namespace>/<id>[:version]`, where version is the major, minor, and patch version of the Template, according to the semver specification.
87+
88+
> **Note:** The `namespace` is a unique identifier for the collection of Templates and must be different than the collection of [Features](./devcontainer-features.md). There are no strict rules for the `namespace`; however, one pattern is to set `namespace` equal to source repository's `<owner>/<repo>`.
89+
90+
A custom media type `application/vnd.devcontainers` and `application/vnd.devcontainers.layer.v1+tar` are used as demonstrated below.
91+
92+
For example, the `go` Template in the `devcontainers/templates` namespace at version `1.2.3` would be pushed to the ghcr.io OCI registry.
93+
94+
> **Note:** The example below uses [`oras`](https://oras.land/) for demonstration purposes. A supporting tool should directly implement the required functionality from the aforementioned OCI artifact distribution specification.
95+
96+
```bash
97+
# ghcr.io/devcontainers/templates/go:1
98+
REGISTRY=ghcr.io
99+
NAMESPACE=devcontainers/templates
100+
TEMPLATE=go
101+
102+
ARTIFACT_PATH=devcontainer-template-go.tgz
103+
104+
for VERSION in 1 1.2 1.2.3 latest
105+
do
106+
oras push ${REGISTRY}/${NAMESPACE}/${TEMPLATE}:${VERSION} \
107+
--manifest-config /dev/null:application/vnd.devcontainers \
108+
./${ARTIFACT_PATH}:application/vnd.devcontainers.layer.v1+tar
109+
done
110+
111+
```
112+
113+
The "namespace" is the globally identifiable name for the collection of Templates. (eg: `owner/repo` for the source code's git repository).
114+
115+
The auto-generated `devcontainer-collection.json` is pushed to the registry with the same `namespace` as above and no accompanying `template` name. The collection file is always tagged as `latest`.
116+
117+
```bash
118+
# ghcr.io/devcontainers/templates
119+
REGISTRY=ghcr.io
120+
NAMESPACE=devcontainers/templates
121+
122+
oras push ${REGISTRY}/${NAMESPACE}:latest \
123+
--manifest-config /dev/null:application/vnd.devcontainers \
124+
./devcontainer-collection.json:application/vnd.devcontainers.collection.layer.v1+json
125+
```

‎proposals/devcontainer-templates.md

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Dev Container Templates reference
2+
3+
Development container "Templates" are source files packaged together that encode configuration for a complete development environment. A Template can be used in a new or existing project, and a [supporting tool](https://containers.dev/supporting) will use the configuration from the Template to build a development container.
4+
5+
The configuration is placed in a [`.devcontainer.json`](/docs/specs/devcontainer-reference.md#devcontainerjson) which can also reference other files within the Template. Alternatively, `.devcontainer/devcontainer.json` can also be used if the container needs to reference other files, such as a `Dockerfile` or `docker-compose.yml`. A Template can also provide additional source files (eg: boilerplate code or a [lifecycle script](https://containers.dev/implementors/json_reference/#lifecycle-scripts).
6+
7+
Template metadata is captured by a `devcontainer-template.json` file in the root folder of the Template.
8+
9+
## Folder structure
10+
11+
A single Template is a folder with at least a `devcontainer-template.json` and [`devcontainer.json`](/docs/specs/devcontainer-reference.md#devcontainerjson). Additional files are permitted and are packaged along side the required files.
12+
13+
```
14+
+-- template
15+
| +-- devcontainer-template.json
16+
| +-- .devcontainer.json
17+
| +-- (other files)
18+
```
19+
20+
## devcontainer-template.json properties
21+
22+
The `devcontainer-template.json` file defines information about the Template to be used by any [supporting tools](../docs/specs/supporting-tools.md#supporting-tools-and-services).
23+
24+
The properties of the file are as follows:
25+
26+
| Property | Type | Description |
27+
| :--- | :--- | :--- |
28+
| `id` | string | ID of the Template. The `id` should be unique in the context of the repository/published package where the Template exists and must match the name of the directory where the `devcontainer-template.json` resides. |
29+
| `name` | string | Name of the Template. |
30+
| `description` | string | Description of the Template. |
31+
| `documentationURL` | string | Url that points to the documentation of the Template. |
32+
| `licenseURL` | string | Url that points to the license of the Template. |
33+
| `type` | string | Type of the dev container (image, dockerfile, dockerCompose) created by the Template. |
34+
| `options` | object | A map of options that the supporting tools should use to populate different configuration options for the Template. |
35+
| `platforms` | object | Languages and platforms supported by the Template. |
36+
| `publisher` | object | Name of the publisher/maintainer of the Template. |
37+
| `keywords` | array | List of strings relevant to a user that would search for this Template. |
38+
39+
### The `options` property
40+
41+
The `options` property contains a map of option IDs and their related configuration settings. These `options` are used by the supporting tools to prompt the user to choose from different Template configuration options. The tools would replace the option ID with the selected value in the specified `replaceIn` files. This replacement would happen before dropping the `.devcontainer.json` (or `.devcontainer/devcontainer.json`) and other files (within the sub-directory of the Template) required to containerize your project. See [option resolution](#option-resolution) for more details. For example:
42+
43+
```json
44+
{
45+
"options": {
46+
"optionId": {
47+
"type": "string",
48+
"description": "Description of the option",
49+
"proposals": ["value1", "value2"],
50+
"default": "value1",
51+
"replaceIn": [".devcontainer.json"],
52+
}
53+
}
54+
}
55+
```
56+
57+
| Property | Type | Description |
58+
| :--- | :--- | :--- |
59+
| `optionId` | string | ID of the option used by the supporting tools to replace the selected value in the specified `replaceIn` files. |
60+
| `optionId.type` | string | Type of the option. Valid types are currently: `boolean`, `string` |
61+
| `optionId.description` | string | Description for the option. |
62+
| `optionId.proposals` | array | A list of suggested string values. Free-form values **are** allowed. Omit when using `optionId.enum`. |
63+
| `optionId.enum` | array | A strict list of allowed string values. Free-form values are **not** allowed. Omit when using `optionId.proposals`. |
64+
| `optionId.default` | string | Default value for the option. |
65+
| `optionId.replaceIn` | array | List of file paths which the supporting tool should use to perform the string replacement of `optionId` with the selected value. The provided path is always relative to the sub-directory of the Template. |
66+
67+
> `Note`: The `options` must be unique for every `devcontainer-template.json`
68+
69+
### Referencing a Template
70+
71+
The `id` format (`<oci-registry>/<namespace>/<template>[:<semantic-version>]`) dictates how a [supporting tool](https://containers.dev/supporting) will locate and download a given Template from an OCI registry. For example:
72+
73+
- `ghcr.io/user/repo/go`
74+
- `ghcr.io/user/repo/go:1`
75+
- `ghcr.io/user/repo/go:latest`
76+
77+
The registry must implement the [OCI Artifact Distribution Specification](https://github.com/opencontainers/distribution-spec). Some implementors can be [found here](https://oras.land/implementors/).
78+
79+
## Versioning
80+
81+
Each Template is individually [versioned according to the semver specification](https://semver.org/). The `version` property in the respective `devcontainer-template.json` file is updated to increment the Template's version.
82+
83+
Tooling that handles releasing Templates will not republish Templates if that exact version has already been published; however, tooling must republish major and minor versions in accordance with the semver specification.
84+
85+
## Release
86+
87+
_For information on distributing Templates, see [devcontainer-templates-distribution.md](./devcontainer-templates-distribution.md)._
88+
89+
### Option Resolution
90+
91+
A Template's `options` property is used by a supporting tool to prompt for different configuration options. A supporting tool will parse the `options` object provided by the user. If a value is selected for a Template, it will be replaced in the provided `replaceIn` files.
92+
93+
### Option resolution example
94+
95+
Consider a `java` Template with the following folder structure:
96+
97+
+-- java
98+
| +-- devcontainer-template.json
99+
| +-- .devcontainer.json
100+
101+
Suppose the `java` Template has the following `options` parameters declared in the `devcontainer-template.json` file:
102+
103+
```json
104+
// ...
105+
"options": {
106+
"imageVariant": {
107+
"type": "string",
108+
"description": "Specify version of java.",
109+
"proposals": [
110+
"17-bullseye",
111+
"17-buster",
112+
"11-bullseye",
113+
"11-buster",
114+
"17",
115+
"11"
116+
],
117+
"default": "17-bullseye",
118+
"replaceIn": [".devcontainer.json"]
119+
},
120+
"nodeVersion": {
121+
"type": "string",
122+
"proposals": [
123+
"latest",
124+
"16",
125+
"14",
126+
"10",
127+
"none"
128+
],
129+
"default": "latest",
130+
"description": "Specify version of node, or 'none' to skip node installation.",
131+
"replaceIn": [".devcontainer.json"]
132+
},
133+
"installMaven": {
134+
"type": "boolean",
135+
"description": "Install Maven, a management tool for Java.",
136+
"default": "false",
137+
"replaceIn": [".devcontainer.json"]
138+
},
139+
}
140+
```
141+
142+
and it has the following `.devcontainer.json` file:
143+
144+
```json
145+
{
146+
"name": "Java",
147+
"image": "mcr.microsoft.com/devcontainers/java:0-${templateOption:imageVariant}",
148+
"features": {
149+
"ghcr.io/devcontainers/features/node:1": {
150+
"version": "${templateOption:nodeVersion}",
151+
"installMaven": "${templateOption:installMaven}"
152+
}
153+
},
154+
// ...
155+
}
156+
```
157+
158+
A user tries to add the `java` Template to their project using the [supporting tools](../docs/specs/supporting-tools.md#supporting-tools-and-services) and selects `17-bullseye` when prompted for `"Specify version of Go"` and the `default` values when prompted for `"Specify version of node, or 'none' to skip node installation"` and `"Install Maven, a management tool for Java"`.
159+
160+
The supporting tool could then use a string replacer (eg. [handlebars](https://handlebarsjs.com/)) for the files mentioned by `replaceIn` property. In this example, `.devcontainer.json` needs to be modified and hence, the inputs can provided to it as follows:
161+
162+
```
163+
{
164+
imageVariant:"17-bullseye",
165+
nodeVersion: "latest",
166+
installMaven: "false"
167+
}
168+
```
169+
170+
The modified `.devcontainer.json` will be as follows:
171+
172+
```json
173+
{
174+
"name": "Go",
175+
"image": "mcr.microsoft.com/devcontainers/go:0-17-bullseye",
176+
"features": {
177+
"ghcr.io/devcontainers/features/node:1": {
178+
"version": "latest",
179+
"installMaven": "false"
180+
}
181+
},
182+
...
183+
}
184+
```
185+
186+
The modified `.devcontainer.json` would be dropped into any existing folder as a starting point for containerizing your project.

0 commit comments

Comments
 (0)