Skip to content

Commit d63ffdf

Browse files
tinesofttinesoft
committed
chore: add devcontainer support to ease developer workstation setup
Fixes #466
1 parent e71ebbc commit d63ffdf

File tree

4 files changed

+206
-0
lines changed

4 files changed

+206
-0
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
2+
// README at: https://github.com/devcontainers/templates/tree/main/src/python
3+
{
4+
"name": "SpecKitDevContainer",
5+
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
6+
"image": "mcr.microsoft.com/devcontainers/python:3.13-trixie", // based on Debian "Trixie" (13)
7+
"features": {
8+
"ghcr.io/devcontainers/features/common-utils:2": {
9+
"installZsh": true,
10+
"installOhMyZsh": true,
11+
"installOhMyZshConfig": true,
12+
"upgradePackages": true,
13+
"username": "devcontainer",
14+
"userUid": "automatic",
15+
"userGid": "automatic"
16+
},
17+
"ghcr.io/devcontainers/features/dotnet:2": {
18+
"version": "lts"
19+
},
20+
"ghcr.io/devcontainers/features/git:1": {
21+
"ppa": true,
22+
"version": "latest"
23+
}
24+
},
25+
26+
// Use 'forwardPorts' to make a list of ports inside the container available locally.
27+
"forwardPorts": [
28+
8080 // for Spec-Kit documentation site
29+
],
30+
"containerUser": "devcontainer",
31+
"updateRemoteUserUID": true,
32+
"postCreateCommand": "chmod +x ./.devcontainer/post-create.sh && ./.devcontainer/post-create.sh",
33+
"postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}",
34+
"customizations": {
35+
"vscode": {
36+
"extensions": [
37+
"mhutchie.git-graph",
38+
"eamodio.gitlens",
39+
"anweber.reveal-button",
40+
"chrisdias.promptboost",
41+
// Github Copilot
42+
"GitHub.copilot",
43+
"GitHub.copilot-chat",
44+
// Codex
45+
"openai.chatgpt",
46+
// Kilo Code
47+
"kilocode.Kilo-Code",
48+
// Roo Code
49+
"RooVeterinaryInc.roo-cline",
50+
// Amazon Developer Q
51+
"AmazonWebServices.amazon-q-vscode"
52+
],
53+
"settings": {
54+
"debug.javascript.autoAttachFilter": "disabled" // fix running commands in integrated terminal
55+
}
56+
}
57+
}
58+
}

‎.devcontainer/post-create.sh‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
#!/bin/bash
2+
3+
# Exit immediately on error, treat unset variables as an error, and fail if any command in a pipeline fails.
4+
set -euo pipefail
5+
6+
# Function to run a command and show logs only on error
7+
run_command() {
8+
local command_to_run="$*"
9+
local output
10+
local exit_code
11+
12+
# Capture all output (stdout and stderr)
13+
output=$(eval "$command_to_run" 2>&1) || exit_code=$?
14+
exit_code=${exit_code:-0}
15+
16+
if [ $exit_code -ne 0 ]; then
17+
echo -e "\033[0;31m[ERROR] Command failed (Exit Code $exit_code): $command_to_run\033[0m" >&2
18+
echo -e "\033[0;31m$output\033[0m" >&2
19+
20+
return $exit_code
21+
fi
22+
}
23+
24+
# Note: We use Bun (instead of npm) as our package manager for its speed and overall efficiency
25+
# It is a drop-in replacement for Node.js, so we can install npm packages through it without issues
26+
echo "📦 Installing Bun Package Manager..."
27+
run_command "curl -fsSL https://bun.sh/install | bash"
28+
run_command "source ~/.bashrc"
29+
echo "✅ Done"
30+
31+
export BUN_INSTALL="$HOME/.bun"
32+
export PATH="$BUN_INSTALL/bin:$PATH"
33+
34+
# Installing CLI-based AI Agents
35+
36+
echo -e "\n🤖 Installing Copilot CLI..."
37+
run_command "bun add --global @github/copilot@latest"
38+
echo "✅ Done"
39+
40+
echo -e "\n🤖 Installing Claude CLI..."
41+
run_command "bun add --global @anthropic-ai/claude-code@latest"
42+
echo "✅ Done"
43+
44+
echo -e "\n🤖 Installing Codex CLI..."
45+
run_command "bun add --global @openai/codex@latest"
46+
echo "✅ Done"
47+
48+
echo -e "\n🤖 Installing Gemini CLI..."
49+
run_command "bun add --global @google/gemini-cli@latest"
50+
echo "✅ Done"
51+
52+
echo -e "\n🤖 Installing Augie CLI..."
53+
run_command "bun add --global @augmentcode/auggie@latest"
54+
echo "✅ Done"
55+
56+
echo -e "\n🤖 Installing Qwen Code CLI..."
57+
run_command "bun add --global @qwen-code/qwen-code@latest"
58+
echo "✅ Done"
59+
60+
echo -e "\n🤖 Installing OpenCode CLI..."
61+
run_command "bun add --global opencode-ai@latest"
62+
echo "✅ Done"
63+
64+
echo -e "\n🤖 Installing Amazon Developer Q CLI..."
65+
run_command "curl --proto '=https' --tlsv1.2 -sSf \"https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip\" -o \"q.zip\""
66+
run_command "unzip q.zip && rm q.zip"
67+
run_command "./q/install.sh --no-confirm"
68+
run_command "rm -rf ./q"
69+
echo "✅ Done"
70+
71+
# Installing UV (Python package manager)
72+
echo -e "\n🐍 Installing UV - Python Package Manager..."
73+
run_command "pipx install uv"
74+
echo "✅ Done"
75+
76+
# Installing DocFx (for documentation site)
77+
echo -e "\n📚 Installing DocFx..."
78+
run_command "dotnet tool update -g docfx"
79+
echo "✅ Done"
80+
81+
echo -e "\n🧹 Cleaning cache..."
82+
run_command "sudo apt-get autoclean"
83+
run_command "sudo apt-get clean"
84+
85+
echo "✅ Setup completed. Happy coding! 🚀"

‎AGENTS.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,51 @@ elif selected_ai == "windsurf":
192192

193193
**Note**: Skip CLI checks for IDE-based agents (Copilot, Windsurf).
194194

195+
#### 7. Update Devcontainer files (Optional)
196+
197+
For agents that have VS Code extensions or require CLI installation, update the devcontainer configuration files:
198+
199+
##### VS Code Extension-based Agents
200+
201+
For agents available as VS Code extensions, add them to `.devcontainer/devcontainer.json`:
202+
203+
```json
204+
{
205+
"customizations": {
206+
"vscode": {
207+
"extensions": [
208+
// ... existing extensions ...
209+
// [New Agent Name]
210+
"[New Agent Extension ID]"
211+
]
212+
}
213+
}
214+
}
215+
```
216+
217+
##### CLI-based Agents
218+
219+
For agents that require CLI tools, add installation commands to `.devcontainer/post-create.sh`:
220+
221+
```bash
222+
#!/bin/bash
223+
224+
# Existing installations...
225+
226+
echo -e "\n🤖 Installing [New Agent Name] CLI..."
227+
# run_command "bun add --global [agent-cli-package]@latest" # Example for node-based CLI
228+
# or other installation instructions (must be non-interactive and compatible with Linux Debian "Trixie" or later)...
229+
echo "✅ Done"
230+
231+
```
232+
233+
**Quick Tips:**
234+
235+
- **Extension-based agents**: Add to the `extensions` array in `devcontainer.json`
236+
- **CLI-based agents**: Add installation scripts to `post-create.sh`
237+
- **Hybrid agents**: May require both extension and CLI installation
238+
- **Test thoroughly**: Ensure installations work in the devcontainer environment
239+
195240
## Agent Categories
196241

197242
### CLI-Based Agents
@@ -201,6 +246,7 @@ Require a command-line tool to be installed:
201246
- **Cursor**: `cursor-agent` CLI
202247
- **Qwen Code**: `qwen` CLI
203248
- **opencode**: `opencode` CLI
249+
- **Amazon Q Developer CLI**: `q` CLI
204250

205251
### IDE-Based Agents
206252
Work within integrated development environments:

‎CONTRIBUTING.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,23 @@ These are one time installations required to be able to test your changes locall
1313
1. Install [Git](https://git-scm.com/downloads)
1414
1. Have an [AI coding agent available](README.md#-supported-ai-agents)
1515

16+
<details>
17+
<summary><b>💡 Hint if you are using <code>VSCode</code> or <code>Github Codespaces</code> as your IDE</b></summary>
18+
19+
<br>
20+
21+
Provided you have [Docker](https://docker.com) installed on your machine, you can leverage [Dev Containers](https://containers.dev) through this [VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), to easily set up your development environment, with aforementioned tools already installed and configured, thanks to the `.devcontainer/devcontainer.json` file (located at the root of the project).
22+
23+
To do so, simply:
24+
25+
- Checkout the repo
26+
- Open it with VSCode
27+
- Open the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) and select "Dev Containers: Open Folder in Container..."
28+
29+
On [Github Codespaces](https://github.com/features/codespaces) it's even simpler, as it leverages the `.devcontainer/devcontainer.json` automatically upon opening the codespace.
30+
31+
</details>
32+
1633
## Submitting a pull request
1734

1835
>[!NOTE]

0 commit comments

Comments
 (0)