|
1 | | -# Dev Container Features: Self Authoring Template |
| 1 | +# Dev Container Features |
2 | 2 |
|
3 | | -> This repo provides a starting point and example for creating your own custom [dev container Features](https://containers.dev/implementors/features/), hosted for free on GitHub Container Registry. The example in this repository follows the [dev container Feature distribution specification](https://containers.dev/implementors/features-distribution/). |
4 | | -> |
5 | | -> To provide feedback to the specification, please leave a comment [on spec issue #70](https://github.com/devcontainers/spec/issues/70). For more broad feedback regarding dev container Features, please see [spec issue #61](https://github.com/devcontainers/spec/issues/61). |
| 3 | +Custom features for dev containers. |
6 | 4 |
|
7 | | -## Example Contents |
| 5 | +## License |
8 | 6 |
|
9 | | -This repository contains a _collection_ of two Features - `hello` and `color`. These Features serve as simple feature implementations. Each sub-section below shows a sample `devcontainer.json` alongside example usage of the Feature. |
10 | | - |
11 | | -### `hello` |
12 | | - |
13 | | -Running `hello` inside the built container will print the greeting provided to it via its `greeting` option. |
14 | | - |
15 | | -```jsonc |
16 | | -{ |
17 | | - "image": "mcr.microsoft.com/devcontainers/base:ubuntu", |
18 | | - "features": { |
19 | | - "ghcr.io/devcontainers/feature-starter/hello:1": { |
20 | | - "greeting": "Hello" |
21 | | - } |
22 | | - } |
23 | | -} |
24 | | -``` |
25 | | - |
26 | | -```bash |
27 | | -$ hello |
28 | | - |
29 | | -Hello, user. |
30 | | -``` |
31 | | - |
32 | | -### `color` |
33 | | - |
34 | | -Running `color` inside the built container will print your favorite color to standard out. |
35 | | - |
36 | | -```jsonc |
37 | | -{ |
38 | | - "image": "mcr.microsoft.com/devcontainers/base:ubuntu", |
39 | | - "features": { |
40 | | - "ghcr.io/devcontainers/feature-starter/color:1": { |
41 | | - "favorite": "green" |
42 | | - } |
43 | | - } |
44 | | -} |
45 | | -``` |
46 | | - |
47 | | -```bash |
48 | | -$ color |
49 | | - |
50 | | -my favorite color is green |
51 | | -``` |
52 | | - |
53 | | -## Repo and Feature Structure |
54 | | - |
55 | | -Similar to the [`devcontainers/features`](https://github.com/devcontainers/features) repo, this repository has a `src` folder. Each Feature has its own sub-folder, containing at least a `devcontainer-feature.json` and an entrypoint script `install.sh`. |
56 | | - |
57 | | -``` |
58 | | -├── src |
59 | | -│ ├── hello |
60 | | -│ │ ├── devcontainer-feature.json |
61 | | -│ │ └── install.sh |
62 | | -│ ├── color |
63 | | -│ │ ├── devcontainer-feature.json |
64 | | -│ │ └── install.sh |
65 | | -| ├── ... |
66 | | -│ │ ├── devcontainer-feature.json |
67 | | -│ │ └── install.sh |
68 | | -... |
69 | | -``` |
70 | | - |
71 | | -An [implementing tool](https://containers.dev/supporting#tools) will composite [the documented dev container properties](https://containers.dev/implementors/features/#devcontainer-feature-json-properties) from the feature's `devcontainer-feature.json` file, and execute in the `install.sh` entrypoint script in the container during build time. Implementing tools are also free to process attributes under the `customizations` property as desired. |
72 | | - |
73 | | -### Options |
74 | | - |
75 | | -All available options for a Feature should be declared in the `devcontainer-feature.json`. The syntax for the `options` property can be found in the [devcontainer Feature json properties reference](https://containers.dev/implementors/features/#devcontainer-feature-json-properties). |
76 | | - |
77 | | -For example, the `color` feature provides an enum of three possible options (`red`, `gold`, `green`). If no option is provided in a user's `devcontainer.json`, the value is set to "red". |
78 | | - |
79 | | -```jsonc |
80 | | -{ |
81 | | - // ... |
82 | | - "options": { |
83 | | - "favorite": { |
84 | | - "type": "string", |
85 | | - "enum": [ |
86 | | - "red", |
87 | | - "gold", |
88 | | - "green" |
89 | | - ], |
90 | | - "default": "red", |
91 | | - "description": "Choose your favorite color." |
92 | | - } |
93 | | - } |
94 | | -} |
95 | | -``` |
96 | | - |
97 | | -Options are exported as Feature-scoped environment variables. The option name is captialized and sanitized according to [option resolution](https://containers.dev/implementors/features/#option-resolution). |
98 | | - |
99 | | -```bash |
100 | | -#!/bin/bash |
101 | | - |
102 | | -echo "Activating feature 'color'" |
103 | | -echo "The provided favorite color is: ${FAVORITE}" |
104 | | - |
105 | | -... |
106 | | -``` |
107 | | - |
108 | | -## Distributing Features |
109 | | - |
110 | | -### Versioning |
111 | | - |
112 | | -Features are individually versioned by the `version` attribute in a Feature's `devcontainer-feature.json`. Features are versioned according to the semver specification. More details can be found in [the dev container Feature specification](https://containers.dev/implementors/features/#versioning). |
113 | | - |
114 | | -### Publishing |
115 | | - |
116 | | -> NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/features-distribution/). |
117 | | -> |
118 | | -> 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. |
119 | | -
|
120 | | -Features are meant to be easily sharable units of dev container configuration and installation code. |
121 | | - |
122 | | -This repo contains a **GitHub Action** [workflow](.github/workflows/release.yaml) that will publish each Feature to GHCR. |
123 | | - |
124 | | -*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/<feature>/README.md` per Feature (which merges any existing `src/<feature>/NOTES.md`). |
125 | | - |
126 | | -By default, each Feature will be prefixed with the `<owner/<repo>` namespace. For example, the two Features in this repository can be referenced in a `devcontainer.json` with: |
127 | | - |
128 | | -``` |
129 | | -ghcr.io/devcontainers/feature-starter/color:1 |
130 | | -ghcr.io/devcontainers/feature-starter/hello:1 |
131 | | -``` |
132 | | - |
133 | | -The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: `ghcr.io/devcontainers/feature-starter`. This contains information useful for tools aiding in Feature discovery. |
134 | | - |
135 | | -'`devcontainers/feature-starter`' is known as the feature collection namespace. |
136 | | - |
137 | | -### Marking Feature Public |
138 | | - |
139 | | -Note that by default, GHCR packages are marked as `private`. To stay within the free tier, Features need to be marked as `public`. |
140 | | - |
141 | | -This can be done by navigating to the Feature's "package settings" page in GHCR, and setting the visibility to 'public`. The URL may look something like: |
142 | | - |
143 | | -``` |
144 | | -https://github.com/users/<owner>/packages/container/<repo>%2F<featureName>/settings |
145 | | -``` |
146 | | - |
147 | | -<img width="669" alt="image" src="https://user-images.githubusercontent.com/23246594/185244705-232cf86a-bd05-43cb-9c25-07b45b3f4b04.png"> |
148 | | - |
149 | | -### Adding Features to the Index |
150 | | - |
151 | | -If you'd like your Features to appear in our [public index](https://containers.dev/features) so that other community members can find them, you can do the following: |
152 | | - |
153 | | -* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io) |
154 | | - * This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site |
155 | | -* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file |
156 | | - |
157 | | -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/features/codespaces) surface Features for their dev container creation UI. |
158 | | - |
159 | | -#### Using private Features in Codespaces |
160 | | - |
161 | | -For any Features hosted in GHCR that are kept private, the `GITHUB_TOKEN` access token in your environment will need to have `package:read` and `contents:read` for the associated repository. |
162 | | - |
163 | | -Many implementing tools use a broadly scoped access token and will work automatically. GitHub Codespaces uses repo-scoped tokens, and therefore you'll need to add the permissions in `devcontainer.json` |
164 | | - |
165 | | -An example `devcontainer.json` can be found below. |
166 | | - |
167 | | -```jsonc |
168 | | -{ |
169 | | - "image": "mcr.microsoft.com/devcontainers/base:ubuntu", |
170 | | - "features": { |
171 | | - "ghcr.io/my-org/private-features/hello:1": { |
172 | | - "greeting": "Hello" |
173 | | - } |
174 | | - }, |
175 | | - "customizations": { |
176 | | - "codespaces": { |
177 | | - "repositories": { |
178 | | - "my-org/private-features": { |
179 | | - "permissions": { |
180 | | - "packages": "read", |
181 | | - "contents": "read" |
182 | | - } |
183 | | - } |
184 | | - } |
185 | | - } |
186 | | - } |
187 | | -} |
188 | | -``` |
| 7 | +[MIT](LICENSE) |
0 commit comments