|
1 | | -# Dev Container Templates: Self Authoring Guide |
2 | | - |
3 | | -> This repo provides a starting point and example for creating your own custom [Dev Container Templates](https://containers.dev/implementors/templates), hosted for free on GitHub Container Registry. The example in this repository follows the [Dev Container Template distribution specification](https://containers.dev/implementors/templates-distribution/). |
4 | | -> |
5 | | -> To provide feedback on the distribution spec, please leave a comment [on spec issue #71](https://github.com/devcontainers/spec/issues/71). |
6 | | -
|
7 | | -## Repo and Template Structure |
8 | | - |
9 | | -This repository contains a _collection_ of two Templates - `hello` and `color`. These Templates serve as simple template implementations which helps containerize the project. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `src` folder. Each Template has its own sub-folder, containing at least a `devcontainer-template.json` and `.devcontainer/devcontainer.json`. |
10 | | - |
11 | | -``` |
12 | | -├── src |
13 | | -│ ├── color |
14 | | -│ │ ├── devcontainer-template.json |
15 | | -│ │ └──| .devcontainer |
16 | | -│ │ └── devcontainer.json |
17 | | -│ ├── hello |
18 | | -│ │ ├── devcontainer-template.json |
19 | | -│ │ └──| .devcontainer |
20 | | -│ │ ├── devcontainer.json |
21 | | -│ │ └── Dockerfile |
22 | | -| ├── ... |
23 | | -│ │ ├── devcontainer-template.json |
24 | | -│ │ └──| .devcontainer |
25 | | -│ │ └── devcontainer.json |
26 | | -├── test |
27 | | -│ ├── color |
28 | | -│ │ └── test.sh |
29 | | -│ ├── hello |
30 | | -│ │ └── test.sh |
31 | | -│ └──test-utils |
32 | | -│ └── test-utils.sh |
33 | | -... |
34 | | -``` |
35 | | - |
36 | | -### Options |
37 | | - |
38 | | -All available options for a Template should be declared in the `devcontainer-template.json`. The syntax for the `options` property can be found in the [devcontainer Template json properties reference](https://containers.dev/implementors/templates#devcontainer-templatejson-properties). |
39 | | - |
40 | | -For example, the `color` Template provides three possible options (`red`, `gold`, `green`), where the default value is set to "red". |
41 | | - |
42 | | -```jsonc |
43 | | -{ |
44 | | - // ... |
45 | | - "options": { |
46 | | - "favorite": { |
47 | | - "type": "string", |
48 | | - "description": "Choose your favorite color." |
49 | | - "proposals": [ |
50 | | - "red", |
51 | | - "gold", |
52 | | - "green" |
53 | | - ], |
54 | | - "default": "red" |
55 | | - } |
56 | | - } |
57 | | -} |
58 | | -``` |
59 | | - |
60 | | -An [implementing tool](https://containers.dev/supporting#tools) will use the `options` property from [the documented Dev Container Template properties](https://containers.dev/implementors/templates#devcontainer-templatejson-properties) for customizing the Template. See [option resolution example](https://containers.dev/implementors/templates#option-resolution-example) for details. |
61 | | - |
62 | | -## Distributing Templates |
63 | | - |
64 | | -**Note**: *Allow GitHub Actions to create and approve pull requests* should be enabled in the repository's `Settings > Actions > General > Workflow permissions` for auto generation of `src/<template>/README.md` per Template (which merges any existing `src/<template>/NOTES.md`). |
65 | | - |
66 | | -### Versioning |
67 | | - |
68 | | -Templates are individually versioned by the `version` attribute in a Template's `devcontainer-template.json`. Templates are versioned according to the semver specification. More details can be found in [the Dev Container Template specification](https://containers.dev/implementors/templates-distribution/#versioning). |
69 | | - |
70 | | -### Publishing |
71 | | - |
72 | | -> NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/templates-distribution/). |
73 | | -> |
74 | | -> While any registry [implementing the OCI Distribution spec](https://github.com/opencontainers/distribution-spec) can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry. |
75 | | -
|
76 | | -Templates are source files packaged together that encode configuration for a complete development environment. |
77 | | - |
78 | | -This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will publish each template to GHCR. By default, each Template will be prefixed with the `<owner/<repo>` namespace. For example, the two Templates in this repository can be referenced by an [implementing tool](https://containers.dev/supporting#tools) with: |
79 | | - |
80 | | -``` |
81 | | -ghcr.io/devcontainers/template-starter/color:latest |
82 | | -ghcr.io/devcontainers/template-starter/hello:latest |
83 | | -``` |
84 | | - |
85 | | -The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: `ghcr.io/devcontainers/template-starter`. This contains information useful for tools aiding in Template discovery. |
86 | | - |
87 | | -'`devcontainers/template-starter`' is known as the template collection namespace. |
88 | | - |
89 | | -### Marking Template Public |
90 | | - |
91 | | -For your Template to be used, it currently needs to be available publicly. By default, OCI Artifacts in GHCR are marked as `private`. |
92 | | - |
93 | | -To make them public, navigate to the Template's "package settings" page in GHCR, and set the visibility to 'public`. |
94 | | - |
95 | | -``` |
96 | | -https://github.com/users/<owner>/packages/container/<repo>%2F<templateName>/settings |
97 | | -``` |
98 | | - |
99 | | -### Adding Templates to the Index |
100 | | - |
101 | | -Next you will need to add your Templates collection to our [public index](https://containers.dev/templates) so that other community members can find them. Just follow these steps once per collection you create: |
102 | | - |
103 | | -* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io) |
104 | | - * This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site |
105 | | -* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file |
106 | | - |
107 | | -This index is from where [supporting tools](https://containers.dev/supporting) like [VS Code Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [GitHub Codespaces](https://github.com/templates/codespaces) surface Templates for their Dev Container Creation Configuration UI. |
108 | | - |
109 | | -### Testing Templates |
110 | | - |
111 | | -This repo contains a GitHub Action [workflow](.github/workflows/test-pr.yaml) for testing the Templates. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `test` folder. Each Template has its own sub-folder, containing at least a `test.sh`. |
112 | | - |
113 | | -For running the tests locally, you would need to execute the following commands - |
114 | | - |
115 | | -``` |
116 | | - ./.github/actions/smoke-test/build.sh ${TEMPLATE-ID} |
117 | | - ./.github/actions/smoke-test/test.sh ${TEMPLATE-ID} |
118 | | -``` |
119 | | - |
120 | | -### Updating Documentation |
121 | | - |
122 | | -This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will automatically generate documentation (ie. `README.md`) for each Template. This file will be auto-generated from the `devcontainer-template.json` and `NOTES.md`. |
| 1 | +# starter-devcontainer |
0 commit comments