Skip to content

Commit 8cd934d

Browse files
CodeMan99CodeMan99
authored
Initial commit
0 parents  commit 8cd934d

File tree

15 files changed

+540
-0
lines changed

15 files changed

+540
-0
lines changed

‎.devcontainer.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"image": "mcr.microsoft.com/devcontainers/javascript-node:0-18",
3+
"customizations": {
4+
"vscode": {
5+
"extensions": [
6+
"mads-hartmann.bash-ide-vscode"
7+
]
8+
}
9+
},
10+
"features": {
11+
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
12+
},
13+
"remoteUser": "node",
14+
"postCreateCommand": "npm install -g @devcontainers/cli"
15+
}

‎.github/workflows/release.yaml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: "Release dev container features & Generate Documentation"
2+
on:
3+
workflow_dispatch:
4+
5+
jobs:
6+
deploy:
7+
if: ${{ github.ref == 'refs/heads/main' }}
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v2
11+
12+
- name: "Publish Features"
13+
uses: devcontainers/action@v1
14+
with:
15+
publish-features: "true"
16+
base-path-to-features: "./src"
17+
generate-docs: "true"
18+
19+
env:
20+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
21+
22+
- name: Create PR for Documentation
23+
id: push_image_info
24+
env:
25+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
26+
run: |
27+
set -e
28+
echo "Start."
29+
# Configure git and Push updates
30+
git config --global user.email [email protected]
31+
git config --global user.name github-actions
32+
git config pull.rebase false
33+
branch=automated-documentation-update-$GITHUB_RUN_ID
34+
git checkout -b $branch
35+
message='Automated documentation update'
36+
# Add / update and commit
37+
git add */**/README.md
38+
git commit -m 'Automated documentation update [skip ci]' || export NO_UPDATES=true
39+
# Push
40+
if [ "$NO_UPDATES" != "true" ] ; then
41+
git push origin "$branch"
42+
gh pr create --title "$message" --body "$message"
43+
fi

‎.github/workflows/test.yaml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: "CI - Test Features"
2+
on:
3+
push:
4+
branches:
5+
- main
6+
pull_request:
7+
workflow_dispatch:
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
continue-on-error: true
13+
strategy:
14+
matrix:
15+
features:
16+
- color
17+
- hello
18+
baseImage:
19+
- debian:latest
20+
- ubuntu:latest
21+
- mcr.microsoft.com/devcontainers/base:ubuntu
22+
steps:
23+
- uses: actions/checkout@v2
24+
25+
- name: "Install latest devcontainer CLI"
26+
run: npm install -g @devcontainers/cli
27+
28+
- name: "Generating tests for '${{ matrix.features }}' against '${{ matrix.baseImage }}'"
29+
run: devcontainer features test -f ${{ matrix.features }} -i ${{ matrix.baseImage }} .
30+
31+
test-global:
32+
runs-on: ubuntu-latest
33+
continue-on-error: true
34+
steps:
35+
- uses: actions/checkout@v2
36+
37+
- name: "Install latest devcontainer CLI"
38+
run: npm install -g @devcontainers/cli
39+
40+
- name: "Testing global scenarios"
41+
run: devcontainer features test --global-scenarios-only .

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2022 Microsoft Corporation
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Dev Container Features: Self Authoring Template
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).
6+
7+
## Example Contents
8+
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. 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:
123+
124+
```
125+
ghcr.io/devcontainers/feature-starter/color:1
126+
ghcr.io/devcontainers/feature-starter/hello:1
127+
```
128+
129+
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.
130+
131+
'`devcontainers/feature-starter`' is known as the feature collection namespace.
132+
133+
### Marking Feature Public
134+
135+
Note that by default, GHCR packages are marked as `private`. To stay within the free tier, Features need to be marked as `public`.
136+
137+
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:
138+
139+
```
140+
https://github.com/users/<owner>/packages/container/<repo>%2F<featureName>/settings
141+
```
142+
143+
<img width="669" alt="image" src="https://user-images.githubusercontent.com/23246594/185244705-232cf86a-bd05-43cb-9c25-07b45b3f4b04.png">
144+
145+
### Adding Features to the Index
146+
147+
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:
148+
149+
* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io)
150+
* This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site
151+
* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file
152+
153+
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.
154+
155+
#### Using private Features in Codespaces
156+
157+
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.
158+
159+
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`
160+
161+
An example `devcontainer.json` can be found below.
162+
163+
```jsonc
164+
{
165+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
166+
"features": {
167+
"ghcr.io/my-org/private-features/hello:1": {
168+
"greeting": "Hello"
169+
}
170+
},
171+
"customizations": {
172+
"codespaces": {
173+
"repositories": {
174+
"my-org/private-features": {
175+
"permissions": {
176+
"packages": "read",
177+
"contents": "read"
178+
}
179+
}
180+
}
181+
}
182+
}
183+
}
184+
```

‎src/color/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
2+
# My Favorite Color (color)
3+
4+
A feature to remind you of your favorite color
5+
6+
## Example Usage
7+
8+
```json
9+
"features": {
10+
"ghcr.io/devcontainers/feature-starter/color:1": {
11+
"version": "latest"
12+
}
13+
}
14+
```
15+
16+
## Options
17+
18+
| Options Id | Description | Type | Default Value |
19+
|-----|-----|-----|-----|
20+
| favorite | Choose your favorite color. | string | red |
21+
22+
23+
24+
---
25+
26+
_Note: This file was auto-generated from the [devcontainer-feature.json](https://github.com/devcontainers/feature-starter/blob/main/src/color/devcontainer-feature.json). Add additional notes to a `NOTES.md`._

‎src/color/devcontainer-feature.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "My Favorite Color",
3+
"id": "color",
4+
"version": "1.0.3",
5+
"description": "A feature to remind you of your favorite color",
6+
"options": {
7+
"favorite": {
8+
"type": "string",
9+
"enum": [
10+
"red",
11+
"gold",
12+
"green"
13+
],
14+
"default": "red",
15+
"description": "Choose your favorite color."
16+
}
17+
}
18+
}

‎src/color/install.sh‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#!/bin/sh
2+
set -e
3+
4+
echo "Activating feature 'color'"
5+
echo "The provided favorite color is: ${FAVORITE}"
6+
7+
cat > /usr/local/bin/color \
8+
<< EOF
9+
#!/bin/sh
10+
echo "my favorite color is ${FAVORITE}"
11+
EOF
12+
13+
chmod +x /usr/local/bin/color

‎src/hello/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
2+
# Hello, World! (hello)
3+
4+
A hello world feature
5+
6+
## Example Usage
7+
8+
```json
9+
"features": {
10+
"ghcr.io/devcontainers/feature-starter/hello:1": {
11+
"version": "latest"
12+
}
13+
}
14+
```
15+
16+
## Options
17+
18+
| Options Id | Description | Type | Default Value |
19+
|-----|-----|-----|-----|
20+
| greeting | Select a pre-made greeting, or enter your own | string | hey |
21+
22+
23+
24+
---
25+
26+
_Note: This file was auto-generated from the [devcontainer-feature.json](https://github.com/devcontainers/feature-starter/blob/main/src/hello/devcontainer-feature.json). Add additional notes to a `NOTES.md`._

0 commit comments

Comments
 (0)