Skip to content

Commit 3aeebe0

Browse files
jonmatumjonmatum
committed
feat: unified shell + sandbox setup with Copier, devcontainer CLI, and robust features
Signed-off-by: Jonatan Mata <[email protected]>
1 parent 2cf40f1 commit 3aeebe0

File tree

6 files changed

+237
-55
lines changed

6 files changed

+237
-55
lines changed

‎LICENSE‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
MIT License
22

33
Copyright (c) 2022 Microsoft Corporation
4+
Copyright (c) 2025 Jonatan Mata
45

56
Permission is hereby granted, free of charge, to any person obtaining a copy
67
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 52 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,23 @@ Modular, portable, and compatible with Amazon Linux, Ubuntu, and Debian-based sy
77
88
## Features Included
99

10-
- **Shell Environment** (Zsh, Oh My Zsh, Powerlevel10k, syntax highlighting, autosuggestions)
10+
- **Shell Environment** – Fully customizable Zsh setup with:
11+
12+
- Zsh and Oh My Zsh
13+
- Powerlevel10k theme
14+
- Zsh autosuggestions and syntax highlighting
15+
- Nerd Font v3 (Meslo)
16+
- Timezone configuration
17+
- Optional opinionated configuration
18+
- Override support via `.zshrc` and `.p10k.zsh` URLs
19+
- Post-install script hook
20+
1121
- **AWS CLI v2**
1222
- **Terraform** (with tfswitch)
1323
- **OpenTofu** (Terraform fork)
1424
- **Python** (via pyenv, with optional pipenv)
1525
- **Node.js** (via nvm)
16-
- **Pre-commit** (Hooks Setup)
26+
- **Pre-commit** (Hooks setup)
1727

1828
Each tool is packaged as an independent, composable DevContainer Feature.
1929

@@ -23,20 +33,34 @@ You can reference features from this repository directly using the `gh:` prefix
2333

2434
```json
2535
{
26-
"features": {
27-
"gh:jonmatum/devcontainer-features/python:1.0.0": {
28-
"version": "3.11.9",
29-
"pipenv": true
30-
},
31-
"gh:jonmatum/devcontainer-features/aws:1.0.0": {},
32-
"gh:jonmatum/devcontainer-features/terraform:1.0.0": {},
33-
"gh:jonmatum/devcontainer-features/shell:1.0.0": {}
36+
"features": {
37+
"gh:jonmatum/devcontainer-features/python:1.0.0": {
38+
"version": "3.11.9",
39+
"pipenv": true
40+
},
41+
"gh:jonmatum/devcontainer-features/aws:1.0.0": {},
42+
"gh:jonmatum/devcontainer-features/terraform:1.0.0": {},
43+
"gh:jonmatum/devcontainer-features/shell:1.1.0": {
44+
"timezone": "America/New_York",
45+
"opinionated": true,
46+
"zshrcUrl": "https://example.com/.zshrc",
47+
"p10kUrl": "https://example.com/.p10k.zsh"
3448
}
49+
}
3550
}
3651
```
3752

3853
Replace the feature ID and version according to your requirements.
3954

55+
## Feature Highlights
56+
57+
Each DevContainer Feature is:
58+
59+
- Composable – Add only the tools you need
60+
- Opinionated, but overridable – Defaults provided, but easy to customize
61+
- Reusable – Designed for local dev, CI/CD, and cloud workspaces
62+
- Tested – Verified against multiple base images and distros
63+
4064
## Structure
4165

4266
Each Feature is organized under the `src/` folder following the DevContainer [Feature distribution specification](https://containers.dev/implementors/features-distribution/).
@@ -46,6 +70,7 @@ src/
4670
shell/
4771
devcontainer-feature.json
4872
install.sh
73+
NOTES.md
4974
aws/
5075
devcontainer-feature.json
5176
install.sh
@@ -65,15 +90,13 @@ src/
6590

6691
## Versioning
6792

68-
Each Feature is individually versioned using the `version` attribute in its `devcontainer-feature.json`.
93+
Each Feature is individually versioned using the `version` attribute in its `devcontainer-feature.json`.
6994
Versioning follows [Semantic Versioning (SemVer)](https://semver.org/).
7095

71-
Example snippet from a Feature:
72-
7396
```json
7497
{
7598
"id": "shell",
76-
"version": "1.0.0",
99+
"version": "1.1.0",
77100
...
78101
}
79102
```
@@ -82,23 +105,31 @@ Releases are automated via GitHub Actions using [release-please](https://github.
82105

83106
## Publishing
84107

85-
Features are automatically published to **GitHub Container Registry (GHCR)** following the [DevContainer Feature distribution spec](https://containers.dev/implementors/features-distribution/).
108+
Features are automatically published to GitHub Container Registry (GHCR) following the [DevContainer Feature distribution spec](https://containers.dev/implementors/features-distribution/).
86109

87110
- Each Feature is published individually under:
88111
`ghcr.io/jonmatum/devcontainer-features/<feature>:<version>`
89-
- A **feature collection metadata package** is also published:
112+
113+
- A collection metadata package is also published:
90114
`ghcr.io/jonmatum/devcontainer-features`
91115

92-
> **Important:** After publishing, Features must be manually marked as **Public** in the GitHub Package settings to be discoverable and usable.
116+
Important: After publishing, Features must be manually marked as **Public** in the GitHub Package settings to be discoverable and usable.
93117

94118
**Example URLs:**
95-
- Feature: `https://github.com/users/jonmatum/packages/container/devcontainer-features/shell`
96-
- Collection: `https://github.com/users/jonmatum/packages/container/devcontainer-features`
119+
120+
- Feature: [Shell Feature Package](https://github.com/users/jonmatum/packages/container/devcontainer-features/shell)
121+
- Collection: [Feature Collection](https://github.com/users/jonmatum/packages/container/devcontainer-features)
97122

98123
## License
99124

100-
Licensed under the [MIT License](LICENSE).
125+
This project is [MIT License](./LICENSE).
126+
Originally scaffolded from Microsoft’s Dev Container Feature starter kit.
127+
Extended and maintained by Jonatan Mata, 2025.
128+
129+
## Additional Resources
130+
131+
For advanced configuration, usage examples, and feature-specific notes, refer to the `NOTES.md` file within each feature’s folder.
101132

102133
---
103134

104-
> echo "Pura Vida & Happy Coding!";
135+
> echo "Pura Vida & Happy Coding!";

‎SANDBOX.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# DevContainer Sandbox Automation
2+
3+
This document outlines how to use the sandbox workflow powered by `Makefile` and [Copier](https://copier.readthedocs.io) to generate and manage a complete development environment based on DevContainer features.
4+
5+
## Overview
6+
7+
The sandbox system is designed for:
8+
9+
- Rapid prototyping of feature combinations
10+
- Reproducible DevContainer setups
11+
- Simplified developer onboarding
12+
13+
### Key Capabilities
14+
15+
- Interactive CLI for selecting image + features
16+
- Auto-generates `.copier-answers.yml`
17+
- Renders `.sandbox/` workspace via Copier
18+
- Builds and launches the container using the `devcontainer` CLI
19+
20+
## Usage
21+
22+
### 1. Interactive Setup
23+
24+
```bash
25+
make interactive
26+
```
27+
28+
Prompts you to select an image and features, then writes a `.copier-answers.yml` file.
29+
30+
### 2. Generate DevContainer
31+
32+
```bash
33+
make sandbox
34+
```
35+
36+
Renders `.sandbox/` from `.template/` using Copier.
37+
Copies selected features from `src/` into `.sandbox/.devcontainer/features/`.
38+
39+
### 3. Launch Container
40+
41+
```bash
42+
make devcontainer-up
43+
```
44+
45+
Uses the official `devcontainer` CLI to build and start the container.
46+
47+
### 4. Run Commands
48+
49+
```bash
50+
make exec CMD="zsh"
51+
```
52+
53+
Executes commands inside the container workspace. Defaults to `zsh`.
54+
55+
## Files & Structure
56+
57+
```
58+
.
59+
├── .copier-answers.yml # Saved feature + image selection
60+
├── .template/ # Copier template (jinja2-powered)
61+
│ └── devcontainer.json.jinja
62+
├── src/ # Feature source directories
63+
├── .sandbox/ # Output devcontainer workspace
64+
└── Makefile # Entrypoint with all tasks
65+
```
66+
67+
## Make Targets
68+
69+
| Command | Description |
70+
| ---------------------- | -------------------------------------------- |
71+
| `make help` | List all available commands |
72+
| `make interactive` | Prompt to choose features + image |
73+
| `make sandbox` | Render devcontainer into `.sandbox/` |
74+
| `make devcontainer-up` | Build and start the container |
75+
| `make exec` | Run command inside container (default `zsh`) |
76+
| `make verify` | Check tool installation in container |
77+
| `make validate` | Check `devcontainer.json` schema compliance |
78+
| `make format` | Format the `devcontainer.json` via `jq` |
79+
80+
## DevContainer CLI Requirement
81+
82+
Make sure you have the [DevContainer CLI](https://containers.dev/implementors/cli/) installed (v0.76+):
83+
84+
```bash
85+
npm install -g @devcontainers/cli
86+
```
87+
88+
## Advanced Notes
89+
90+
- If Copier is not installed, the `Makefile` bootstraps it into a local virtualenv
91+
- Answer files are reusable across environments and stored at `.copier-answers.yml`
92+
- Additional validation and formatting tooling is built into the Make targets

‎src/shell/NOTES.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Devcontainer Shell Feature
2+
3+
This repository provides a fully-automated shell environment for DevContainers using:
4+
5+
- Zsh with Oh My Zsh, Powerlevel10k, and plugins
6+
- Meslo Nerd Font v3 installer
7+
- Cross-platform timezone support
8+
- Customizable opinionated dotfiles
9+
- Post-install script hook
10+
- Smart feature summary at the end
11+
12+
## Features Included
13+
14+
### Shell Environment Options
15+
16+
| Option | Type | Default | Description |
17+
| ---------------------- | ------- | ------- | --------------------------------------------------------------------------------------- |
18+
| `installZsh` | boolean | `true` | Install Zsh and set it as the default shell. |
19+
| `ohMyZsh` | boolean | `true` | Install [Oh My Zsh](https://ohmyz.sh). |
20+
| `powerlevel10k` | boolean | `true` | Install [Powerlevel10k](https://github.com/romkatv/powerlevel10k). |
21+
| `autosuggestions` | boolean | `true` | Enable [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions). |
22+
| `syntaxHighlighting` | boolean | `true` | Enable [zsh-syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting). |
23+
| `nerdFont` | boolean | `true` | Install Meslo Nerd Font v3.0.2 locally in user fonts. |
24+
| `timezone` | string | `UTC` | Set system timezone (e.g. `Europe/Paris`). |
25+
| `opinionated` | boolean | `false` | Apply curated `.zshrc` and `.p10k.zsh` configuration. |
26+
| `zshrcUrl` | string | `""` | Custom `.zshrc` URL (overrides opinionated default). |
27+
| `p10kUrl` | string | `""` | Custom `.p10k.zsh` URL (overrides opinionated default). |
28+
| `postInstallScriptUrl` | string | `""` | Optional URL to a bash script to execute after setup. |
29+
30+
## Meslo Nerd Font Installer
31+
32+
Installs [Meslo Nerd Font v3.0.2](https://github.com/ryanoasis/nerd-fonts) into `~/.local/share/fonts`.
33+
34+
- Supports Debian, Alpine, and Amazon Linux
35+
- Verifies and installs required tools: `curl`, `unzip`, `fontconfig`
36+
- Runs `fc-cache` to refresh fonts
37+
38+
## Timezone Configuration
39+
40+
If `timezone` is set:
41+
42+
- Symlinks `/etc/localtime` to the correct zoneinfo file
43+
- Writes to `/etc/timezone`
44+
- Installs `tzdata` if necessary (Debian-based systems)
45+
46+
Example:
47+
48+
```json
49+
"timezone": "America/Costa_Rica"
50+
```
51+
52+
## Opinionated Dotfiles
53+
54+
If `opinionated=true`, the following behavior is applied:
55+
56+
- `.zshrc` and `.p10k.zsh` are downloaded from curated Gist URLs
57+
- These can be overridden with `zshrcUrl` and `p10kUrl`
58+
- Adds `POWERLEVEL9K_DISABLE_CONFIGURATION_WIZARD=true` to prevent interactive wizard
59+
60+
## Post-Install Script Support
61+
62+
A custom shell script can be executed automatically:
63+
64+
```json
65+
"postInstallScriptUrl": "https://example.com/my-extra-setup.sh"
66+
```
67+
68+
This script will be downloaded and executed after the rest of the feature setup.
69+
70+
## Final Setup Summary
71+
72+
At the end of setup, a status table will be printed summarizing all enabled tools:
73+
74+
```
75+
> Setup Summary:
76+
77+
Zsh ✔ Installed zsh 5.9
78+
Oh My Zsh ✔ Installed Enabled
79+
Powerlevel10k ✔ Installed Enabled
80+
Nerd Font ✔ Installed MesloLGS NF
81+
Autosuggestions ✔ Installed Enabled
82+
Syntax Highlighting ✔ Installed Enabled
83+
Opinionated Config ✔ Installed Custom .zshrc and .p10k.zsh used
84+
85+
✔ Shell environment setup complete for user
86+
```
87+
88+
---
89+
90+
> For sandbox and template automation via Make + Copier, see [`SANDBOX.md`](../../SANDBOX.md).

‎src/shell/README.md‎

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎src/shell/devcontainer-feature.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"id": "shell",
3-
"version": "1.1.2",
3+
"version": "1.2.0",
44
"name": "Shell Setup",
55
"description": "Configurable shell setup with optional Zsh, Oh My Zsh, Powerlevel10k, autosuggestions, and syntax highlighting.",
66
"options": {
@@ -60,4 +60,4 @@
6060
"description": "Optional URL to a bash script to execute at the end of the setup."
6161
}
6262
}
63-
}
63+
}

0 commit comments

Comments
 (0)