Skip to content

docs: improve readme #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 9 commits into from
Closed

docs: improve readme #24

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
8c28751
wip: add readme header placeholder
jcbhmr May 31, 2023
9380ad3
Add usage section
jcbhmr Jun 6, 2023
134b1f3
Add development section
jcbhmr Jun 6, 2023
fb2b059
Merge branch 'main' into 6-improve-readme
jcbhmr Jun 9, 2023
7fa16b5
line ending
jcbhmr Jun 13, 2023
1253f85
Remove under construction banner
jcbhmr Jun 13, 2023
9347694
add back construction header with lint disable rules
jcbhmr Jun 13, 2023
49674cd
Add alt text to header image
jcbhmr Jun 13, 2023
aa0c80c
Merge branch 'main' into 6-improve-readme
jcbhmr Jun 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 53 additions & 159 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,186 +1,80 @@
![🚧 Under construction 👷‍♂️](https://i.imgur.com/LEP2R3N.png)

# Dev Container Features: Self Authoring Template

> 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/).
>
> 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).

## Example Contents

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.

### `hello`

Running `hello` inside the built container will print the greeting provided to it via its `greeting` option.

```jsonc
{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/devcontainers/feature-starter/hello:1": {
"greeting": "Hello"
}
}
}
```

```bash
$ hello
<!-- markdownlint-disable MD041 MD033 -->

Hello, user.
```

### `color`
![🚧 Under construction 👷‍♂️](https://i.imgur.com/LEP2R3N.png)

Running `color` inside the built container will print your favorite color to standard out.
# Devcontainer community features

```jsonc
{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/devcontainers/feature-starter/color:1": {
"favorite": "green"
}
}
}
```
🧰 Community-driven collection of addons for [@devcontainers]

```bash
$ color
<div align="center">

my favorite color is green
```
![Code demo](https://i.imgur.com/Gz9yWx8.png)

## Repo and Feature Structure
[Docs website](https://devcontainers-community.github.io/features/)
| [Official feature index](https://containers.dev/features)

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`.
</div>

```
├── src
│ ├── hello
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
│ ├── color
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
| ├── ...
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
...
```
➕ Add extra features to your GitHub Codespace \
🐳 Use JSON, not `Dockerfile`s! \
👨‍👩‍👧‍👦 Community-driven maintainership

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.
**🤝 We want you!** If you're a community devcontainer feature maintainer, we'd
love to add you to this project! ❤️ If you just want to hand off a devcontainer
feature that you no longer want to maintain, **that's perfect too**. Open a
[Discussion] and let's have a friendly chat. 😊

### Options
## Usage

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).
![JSON](https://img.shields.io/static/v1?style=for-the-badge&message=JSON&color=000000&logo=JSON&logoColor=FFFFFF&label=)
![GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub+Codespaces&color=181717&logo=GitHub&logoColor=FFFFFF&label=)
![devcontainers](https://img.shields.io/static/v1?style=for-the-badge&message=devcontainers&color=2496ED&logo=Docker&logoColor=FFFFFF&label=)

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".
Add a `features: {}` key to your existing `devcontainer.json` file, or make a
new one at `.devcontainer/devcontainer.json` in your repository. Then, just add
[one of the features that we offer] to the object map with an optional `{}`
options object.

```jsonc
// .devcontainer/devcontainer.json
{
// ...
"options": {
"favorite": {
"type": "string",
"enum": [
"red",
"gold",
"green"
],
"default": "red",
"description": "Choose your favorite color."
}
}
"features": {
"ghcr.io/devcontainers-community/features/dart": {}
}
}
```

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).

```bash
#!/bin/bash

echo "Activating feature 'color'"
echo "The provided favorite color is: ${FAVORITE}"

...
```

## Distributing Features

### Versioning
[📚 Read more about each feature on our documentation website!](https://devcontainers-community.github.io/features/)

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).
## Development

### Publishing
![Devcontainers](https://img.shields.io/static/v1?style=for-the-badge&message=Devcontainers&color=2496ED&logo=Docker&logoColor=FFFFFF&label=)
![Bash](https://img.shields.io/static/v1?style=for-the-badge&message=Bash&color=4EAA25&logo=GNU+Bash&logoColor=FFFFFF&label=)

> NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/features-distribution/).
>
> 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.
🐣 The @devcontainers-community organization is still in its early stages. This
features repository is currently trying to **hit the highlights first**. That
means popular features first! If you notice a bug 🐛 or have an improvement
suggestion 💡 we'd love to hear it! 😍

Features are meant to be easily sharable units of dev container configuration and installation code.
If you're interested in getting started modifying, adding, or testing a template
in this repository, you can do so without even leaving your browser thanks to
GitHub Codespaces! ☁️ After optionally forking the repository, you just hit the
green Code button at the top of the GitHub web UI and then Create codespace on
main. 🚀

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:

```
ghcr.io/devcontainers/feature-starter/color:1
ghcr.io/devcontainers/feature-starter/hello:1
```
After launching your dev environment and making some changes, you're probably
going to want to test those changes. Run the `devcontainer features test`
command to run _all_ the tests, or just `-f` to run a specific one that you're
working on. Be warned that this involves some heavyweight Docker-ing around!

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.

'`devcontainers/feature-starter`' is known as the feature collection namespace.

### Marking Feature Public

Note that by default, GHCR packages are marked as `private`. To stay within the free tier, Features need to be marked as `public`.

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:

```
https://github.com/users/<owner>/packages/container/<repo>%2F<featureName>/settings
```sh
devcontainer features test
```

<img width="669" alt="image" src="https://user-images.githubusercontent.com/23246594/185244705-232cf86a-bd05-43cb-9c25-07b45b3f4b04.png">
🤝 Check out our contributing guide to see how to get your changes merged!

### Adding Features to the Index

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:

* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io)
* This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site
* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file

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.

#### Using private Features in Codespaces

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.

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`

An example `devcontainer.json` can be found below.

```jsonc
{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/my-org/private-features/hello:1": {
"greeting": "Hello"
}
},
"customizations": {
"codespaces": {
"repositories": {
"my-org/private-features": {
"permissions": {
"packages": "read",
"contents": "read"
}
}
}
}
}
}
```
<!-- prettier-ignore-start -->
[@devcontainers]: https://github.com/devcontainers
[one of the features that we offer]: https://devcontainers-community.github.io/features/
[Discussion]: https://github.com/devcontainers-community/features/discussions/new?category=general
<!-- prettier-ignore-end -->