Skip to content

Commit

Permalink
feat: git-subtree
Browse files Browse the repository at this point in the history
  • Loading branch information
@realSergiy
realSergiy committed Mar 19, 2024
1 parent 945151d commit a73ed4a
Show file tree
Hide file tree
Showing 10 changed files with 273 additions and 308 deletions.
190 changes: 6 additions & 184 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,188 +1,10 @@
# Dev Container Features: Self Authoring Template
# Dev Container Features by @realSergiy

> 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).
This repo contains a _collection_ of custom [Dev Container Features](https://containers.dev/implementors/features/) and is based on the [starter template](https://github.com/devcontainers/feature-starter)

## Example Contents
## 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.
### [`git subtree`](https://manpages.debian.org/testing/git-man/git-subtree.1.en.html)

### `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

Hello, user.
```

### `color`

Running `color` inside the built container will print your favorite color to standard out.

```jsonc
{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/devcontainers/feature-starter/color:1": {
"favorite": "green"
}
}
}
```

```bash
$ color

my favorite color is green
```

## Repo and Feature Structure

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

```
├── src
│ ├── hello
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
│ ├── color
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
| ├── ...
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
...
```

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.

### Options

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

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

```jsonc
{
// ...
"options": {
"favorite": {
"type": "string",
"enum": [
"red",
"gold",
"green"
],
"default": "red",
"description": "Choose your favorite color."
}
}
}
```

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

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

### Publishing

> 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.
Features are meant to be easily sharable units of dev container configuration and installation code.

This repo contains a **GitHub Action** [workflow](.github/workflows/release.yaml) that will publish each Feature to GHCR.

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

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
```

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
```

<img width="669" alt="image" src="https://user-images.githubusercontent.com/23246594/185244705-232cf86a-bd05-43cb-9c25-07b45b3f4b04.png">

### 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"
}
}
}
}
}
}
```
Allows to drag, modify and merge replicas of a git repository that has been dragged into the main repository.
[Read more...](https://gist.github.com/SKempin/b7857a6ff6bddb05717cc17a44091202)
198 changes: 198 additions & 0 deletions lib/library_scripts.sh
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
#!/bin/bash -i

# MIT License
#
# Copyright (c) 2022 devcontainers-contrib
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

clean_download() {
# The purpose of this function is to download a file with minimal impact on contaier layer size
# this means if no valid downloader is found (curl or wget) then we install a downloader (currently wget) in a
# temporary manner, and making sure to
# 1. uninstall the downloader at the return of the function
# 2. revert back any changes to the package installer database/cache (for example apt-get lists)
# The above steps will minimize the leftovers being created while installing the downloader
# Supported distros:
# debian/ubuntu/alpine

url=$1
output_location=$2
tempdir=$(mktemp -d)
downloader_installed=""

function _apt_get_install() {
tempdir=$1

# copy current state of apt list - in order to revert back later (minimize contianer layer size)
cp -p -R /var/lib/apt/lists $tempdir
apt-get update -y
apt-get -y install --no-install-recommends wget ca-certificates
}

function _apt_get_cleanup() {
tempdir=$1

echo "removing wget"
apt-get -y purge wget --auto-remove

echo "revert back apt lists"
rm -rf /var/lib/apt/lists/*
rm -r /var/lib/apt/lists && mv $tempdir/lists /var/lib/apt/lists
}

function _apk_install() {
tempdir=$1
# copy current state of apk cache - in order to revert back later (minimize contianer layer size)
cp -p -R /var/cache/apk $tempdir

apk add --no-cache wget
}

function _apk_cleanup() {
tempdir=$1

echo "removing wget"
apk del wget
}
# try to use either wget or curl if one of them already installer
if type curl >/dev/null 2>&1; then
downloader=curl
elif type wget >/dev/null 2>&1; then
downloader=wget
else
downloader=""
fi

# in case none of them is installed, install wget temporarly
if [ -z $downloader ] ; then
if [ -x "/usr/bin/apt-get" ] ; then
_apt_get_install $tempdir
elif [ -x "/sbin/apk" ] ; then
_apk_install $tempdir
else
echo "distro not supported"
exit 1
fi
downloader="wget"
downloader_installed="true"
fi

if [ $downloader = "wget" ] ; then
wget -q $url -O $output_location
else
curl -sfL $url -o $output_location
fi

# NOTE: the cleanup procedure was not implemented using `trap X RETURN` only because
# alpine lack bash, and RETURN is not a valid signal under sh shell
if ! [ -z $downloader_installed ] ; then
if [ -x "/usr/bin/apt-get" ] ; then
_apt_get_cleanup $tempdir
elif [ -x "/sbin/apk" ] ; then
_apk_cleanup $tempdir
else
echo "distro not supported"
exit 1
fi
fi

}


ensure_nanolayer() {
# Ensure existance of the nanolayer cli program
local variable_name=$1

local required_version=$2
# normalize version
if ! [[ $required_version == v* ]]; then
required_version=v$required_version
fi

local nanolayer_location=""

# If possible - try to use an already installed nanolayer
if [[ -z "${NANOLAYER_FORCE_CLI_INSTALLATION}" ]]; then
if [[ -z "${NANOLAYER_CLI_LOCATION}" ]]; then
if type nanolayer >/dev/null 2>&1; then
echo "Found a pre-existing nanolayer in PATH"
nanolayer_location=nanolayer
fi
elif [ -f "${NANOLAYER_CLI_LOCATION}" ] && [ -x "${NANOLAYER_CLI_LOCATION}" ] ; then
nanolayer_location=${NANOLAYER_CLI_LOCATION}
echo "Found a pre-existing nanolayer which were given in env variable: $nanolayer_location"
fi

# make sure its of the required version
if ! [[ -z "${nanolayer_location}" ]]; then
local current_version
current_version=$($nanolayer_location --version)
if ! [[ $current_version == v* ]]; then
current_version=v$current_version
fi

if ! [ $current_version == $required_version ]; then
echo "skipping usage of pre-existing nanolayer. (required version $required_version does not match existing version $current_version)"
nanolayer_location=""
fi
fi

fi

# If not previuse installation found, download it temporarly and delete at the end of the script
if [[ -z "${nanolayer_location}" ]]; then

if [ "$(uname -sm)" == "Linux x86_64" ] || [ "$(uname -sm)" == "Linux aarch64" ]; then
tmp_dir=$(mktemp -d -t nanolayer-XXXXXXXXXX)

clean_up () {
ARG=$?
rm -rf $tmp_dir
exit $ARG
}
trap clean_up EXIT


if [ -x "/sbin/apk" ] ; then
clib_type=musl
else
clib_type=gnu
fi

tar_filename=nanolayer-"$(uname -m)"-unknown-linux-$clib_type.tgz

# clean download will minimize leftover in case a downloaderlike wget or curl need to be installed
clean_download https://github.com/devcontainers-contrib/cli/releases/download/$required_version/$tar_filename $tmp_dir/$tar_filename

tar xfzv $tmp_dir/$tar_filename -C "$tmp_dir"
chmod a+x $tmp_dir/nanolayer
nanolayer_location=$tmp_dir/nanolayer


else
echo "No binaries compiled for non-x86-linux architectures yet: $(uname -m)"
exit 1
fi
fi

# Expose outside the resolved location
declare -g ${variable_name}=$nanolayer_location

}
Loading

0 comments on commit a73ed4a

Please sign in to comment.