Compare commits
13 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 271dc2eb35 | |||
| 875afe0039 | |||
| 9e381ebe32 | |||
| 3e048218c3 | |||
| 6ecd65d18d | |||
| e58962a72c | |||
| d2c0447147 | |||
| 77a7daf67f | |||
| b3cfe641bb | |||
| f7bd21b9fe | |||
| 1b97d98155 | |||
| de659fbc54 | |||
| d651a084de |
@@ -105,21 +105,21 @@ jobs:
|
|||||||
|
|
||||||
- name: Update Docker Hub description
|
- name: Update Docker Hub description
|
||||||
run: |
|
run: |
|
||||||
TOKEN=$(curl -s -X POST https://hub.docker.com/v2/users/login/ \
|
TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{"username":"${{ vars.DOCKERHUB_USERNAME }}","password":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
|
-d '{"identifier":"${{ vars.DOCKERHUB_USERNAME }}","secret":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
|
||||||
| jq -r .token)
|
| jq -r .access_token)
|
||||||
if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
|
if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
|
||||||
echo "::error::Failed to authenticate with Docker Hub API"
|
echo "::error::Failed to authenticate with Docker Hub API"
|
||||||
exit 1
|
exit 1
|
||||||
fi
|
fi
|
||||||
HTTP_CODE=$(jq -n \
|
HTTP_CODE=$(jq -n \
|
||||||
--rawfile full DOCKER_HUB.md \
|
--rawfile full DOCKER_HUB.md \
|
||||||
--arg short "Portable AI dev environment for opencode. Debian-based with git, Node.js, AWS CLI, and SSH support. Available in base and omos (multi-agent) variants." \
|
--arg short "Portable AI dev environment for opencode. Debian-based with git, Node.js, AWS CLI, and SSH support." \
|
||||||
'{"full_description": $full, "description": $short}' | \
|
'{"full_description": $full, "description": $short}' | \
|
||||||
curl -s -o /tmp/hub-response.txt -w "%{http_code}" -X PATCH \
|
curl -s -o /tmp/hub-response.txt -w "%{http_code}" -X PATCH \
|
||||||
"https://hub.docker.com/v2/repositories/${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox/" \
|
"https://hub.docker.com/v2/repositories/${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox/" \
|
||||||
-H "Authorization: JWT $TOKEN" \
|
-H "Authorization: Bearer $TOKEN" \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d @-)
|
-d @-)
|
||||||
echo "Docker Hub API returned: $HTTP_CODE"
|
echo "Docker Hub API returned: $HTTP_CODE"
|
||||||
|
|||||||
+139
-5
@@ -116,10 +116,22 @@ The entrypoint automatically detects the owner of `/workspace` and adjusts the c
|
|||||||
|
|
||||||
## Initial Setup
|
## Initial Setup
|
||||||
|
|
||||||
### 1. Create a project directory
|
### 1. Create host directories
|
||||||
|
|
||||||
|
Bind-mounted directories must exist on the host before starting the container. Docker creates missing directories as root-owned, which causes permission issues.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# Required
|
||||||
mkdir -p ~/projects
|
mkdir -p ~/projects
|
||||||
|
|
||||||
|
# If mounting opencode config (recommended for persistent settings)
|
||||||
|
mkdir -p ~/.config/opencode
|
||||||
|
|
||||||
|
# If using AWS Bedrock
|
||||||
|
# mkdir -p ~/.aws
|
||||||
|
|
||||||
|
# If mounting neovim config
|
||||||
|
# mkdir -p ~/.config/nvim
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Create a `.env` file
|
### 2. Create a `.env` file
|
||||||
@@ -145,7 +157,7 @@ GIT_USER_EMAIL=you@example.com
|
|||||||
**AWS Bedrock (SSO):**
|
**AWS Bedrock (SSO):**
|
||||||
```bash
|
```bash
|
||||||
OPENCODE_PROVIDER=amazon-bedrock
|
OPENCODE_PROVIDER=amazon-bedrock
|
||||||
OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
|
OPENCODE_MODEL=amazon-bedrock/eu.anthropic.claude-opus-4-6-v1
|
||||||
AWS_REGION=eu-west-1
|
AWS_REGION=eu-west-1
|
||||||
AWS_PROFILE=your-profile-name
|
AWS_PROFILE=your-profile-name
|
||||||
GIT_USER_NAME=Your Name
|
GIT_USER_NAME=Your Name
|
||||||
@@ -184,6 +196,10 @@ Understanding what survives container restarts and what doesn't:
|
|||||||
| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes — lives on host | SSH keys |
|
| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes — lives on host | SSH keys |
|
||||||
| `/home/developer/.aws` | Host bind mount | ✅ Yes — lives on host | AWS credentials/SSO cache |
|
| `/home/developer/.aws` | Host bind mount | ✅ Yes — lives on host | AWS credentials/SSO cache |
|
||||||
| `/home/developer/.local/share/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | Session history, memory, auth tokens |
|
| `/home/developer/.local/share/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | Session history, memory, auth tokens |
|
||||||
|
| `/home/developer/.local/share/uv` | Named volume (if configured) | ✅ Yes — Docker volume | Python installs, uv tool installs |
|
||||||
|
| `/home/developer/.rustup` | Named volume (if configured) | ✅ Yes — Docker volume | Rust toolchains |
|
||||||
|
| `/home/developer/.cargo` | Named volume (if configured) | ✅ Yes — Docker volume | Cargo binaries, registry cache |
|
||||||
|
| `/home/developer/.vscode-server` | Named volume (if configured) | ✅ Yes — Docker volume | VS Code server and extensions |
|
||||||
| `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes — lives on host | opencode.json, oh-my-opencode-slim.json, skills |
|
| `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes — lives on host | opencode.json, oh-my-opencode-slim.json, skills |
|
||||||
|
|
||||||
### Key points
|
### Key points
|
||||||
@@ -191,6 +207,8 @@ Understanding what survives container restarts and what doesn't:
|
|||||||
- **Project files** (`/workspace`) are always safe — they're your host filesystem.
|
- **Project files** (`/workspace`) are always safe — they're your host filesystem.
|
||||||
- **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start if no existing config is found. To persist config changes, mount the config directory from the host (see Custom opencode Config below).
|
- **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start if no existing config is found. To persist config changes, mount the config directory from the host (see Custom opencode Config below).
|
||||||
- **opencode data** (session history, memory) is lost with `--rm` unless you add a named volume.
|
- **opencode data** (session history, memory) is lost with `--rm` unless you add a named volume.
|
||||||
|
- **Python installs** via `uv python install` are lost unless you add the `devbox-uv` named volume.
|
||||||
|
- **Rust toolchains** via `rustup-init` are lost unless you add the `devbox-rustup` and `devbox-cargo` named volumes.
|
||||||
- **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users).
|
- **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users).
|
||||||
|
|
||||||
## Custom opencode Config
|
## Custom opencode Config
|
||||||
@@ -217,6 +235,111 @@ docker run -it --rm \
|
|||||||
joakimp/opencode-devbox:latest
|
joakimp/opencode-devbox:latest
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Python Development with uv
|
||||||
|
|
||||||
|
The image includes [uv](https://docs.astral.sh/uv/), a fast Python package manager that replaces pip, venv, and pyenv. Python is not pre-installed but can be installed on demand:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install Python (persists across restarts with devbox-uv volume)
|
||||||
|
uv python install 3.14
|
||||||
|
|
||||||
|
# Create a virtual environment and install dependencies
|
||||||
|
uv venv
|
||||||
|
uv pip install -r requirements.txt
|
||||||
|
|
||||||
|
# Or use uv's project workflow (reads pyproject.toml)
|
||||||
|
uv sync
|
||||||
|
|
||||||
|
# Run a Python script
|
||||||
|
uv run python script.py
|
||||||
|
|
||||||
|
# Install standalone Python tools
|
||||||
|
uvx ruff check .
|
||||||
|
```
|
||||||
|
|
||||||
|
To persist Python installs across container restarts, add a named volume:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run -it --rm \
|
||||||
|
-v devbox-uv:/home/developer/.local/share/uv \
|
||||||
|
... \
|
||||||
|
joakimp/opencode-devbox:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
Project virtual environments (`.venv`) are stored in your workspace directory and persist automatically via the `/workspace` bind mount.
|
||||||
|
|
||||||
|
## Rust Development with rustup
|
||||||
|
|
||||||
|
The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# One-time setup: install Rust toolchain (~300MB, persists with volumes)
|
||||||
|
rustup-init -y
|
||||||
|
source ~/.cargo/env
|
||||||
|
|
||||||
|
# Now use Rust normally
|
||||||
|
cargo new my-project
|
||||||
|
cargo build
|
||||||
|
cargo run
|
||||||
|
```
|
||||||
|
|
||||||
|
To persist Rust toolchains and cargo data across container restarts, add named volumes:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run -it --rm \
|
||||||
|
-v devbox-rustup:/home/developer/.rustup \
|
||||||
|
-v devbox-cargo:/home/developer/.cargo \
|
||||||
|
... \
|
||||||
|
joakimp/opencode-devbox:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
## JavaScript and TypeScript
|
||||||
|
|
||||||
|
The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Initialize a new project
|
||||||
|
npm init -y
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
npm install
|
||||||
|
|
||||||
|
# Run TypeScript (via tsx, ts-node, etc.)
|
||||||
|
npx tsx src/index.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
The OMOS image variant also includes **Bun**, a faster JavaScript runtime and package manager:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bun init
|
||||||
|
bun install
|
||||||
|
bun run src/index.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
Node modules are stored in your project directory under `/workspace` and persist automatically.
|
||||||
|
|
||||||
|
## VS Code Integration
|
||||||
|
|
||||||
|
VS Code can connect directly to a running opencode-devbox container for a full IDE experience with IntelliSense, debugging, and extensions running inside the container.
|
||||||
|
|
||||||
|
**Requirements:** Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. For remote Docker hosts, also install [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).
|
||||||
|
|
||||||
|
**Steps:**
|
||||||
|
|
||||||
|
1. Start the container: `docker compose up -d`
|
||||||
|
2. In VS Code: `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container" → select `opencode-devbox`
|
||||||
|
|
||||||
|
For remote Docker hosts (e.g. connecting to a server via SSH), first connect to the remote host with Remote-SSH, then attach to the container from there.
|
||||||
|
|
||||||
|
VS Code extensions installed inside the container persist as long as the container exists. For persistent extension storage across container recreations, add a named volume:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run -it --rm \
|
||||||
|
-v devbox-vscode:/home/developer/.vscode-server \
|
||||||
|
... \
|
||||||
|
joakimp/opencode-devbox:latest
|
||||||
|
```
|
||||||
|
|
||||||
## Using docker-compose
|
## Using docker-compose
|
||||||
|
|
||||||
Create a directory with a `docker-compose.yml` and a `.env` file:
|
Create a directory with a `docker-compose.yml` and a `.env` file:
|
||||||
@@ -229,7 +352,7 @@ mkdir opencode-devbox && cd opencode-devbox
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
OPENCODE_PROVIDER=amazon-bedrock
|
OPENCODE_PROVIDER=amazon-bedrock
|
||||||
OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
|
OPENCODE_MODEL=amazon-bedrock/eu.anthropic.claude-opus-4-6-v1
|
||||||
AWS_REGION=eu-west-1
|
AWS_REGION=eu-west-1
|
||||||
AWS_PROFILE=your-profile-name
|
AWS_PROFILE=your-profile-name
|
||||||
GIT_USER_NAME=Your Name
|
GIT_USER_NAME=Your Name
|
||||||
@@ -254,6 +377,13 @@ services:
|
|||||||
- ~/projects:/workspace
|
- ~/projects:/workspace
|
||||||
- ~/.ssh:/home/developer/.ssh:ro
|
- ~/.ssh:/home/developer/.ssh:ro
|
||||||
- devbox-data:/home/developer/.local/share/opencode
|
- devbox-data:/home/developer/.local/share/opencode
|
||||||
|
# Optional: persist Python/uv installs across restarts
|
||||||
|
# - devbox-uv:/home/developer/.local/share/uv
|
||||||
|
# Optional: persist Rust toolchains and cargo data
|
||||||
|
# - devbox-rustup:/home/developer/.rustup
|
||||||
|
# - devbox-cargo:/home/developer/.cargo
|
||||||
|
# Optional: persist VS Code server and extensions
|
||||||
|
# - devbox-vscode:/home/developer/.vscode-server
|
||||||
# Mount AWS config for Bedrock SSO (required for amazon-bedrock provider)
|
# Mount AWS config for Bedrock SSO (required for amazon-bedrock provider)
|
||||||
# - ~/.aws:/home/developer/.aws
|
# - ~/.aws:/home/developer/.aws
|
||||||
# Optional: mount opencode config directory (persists config changes across restarts)
|
# Optional: mount opencode config directory (persists config changes across restarts)
|
||||||
@@ -265,6 +395,10 @@ services:
|
|||||||
|
|
||||||
volumes:
|
volumes:
|
||||||
devbox-data:
|
devbox-data:
|
||||||
|
# devbox-uv:
|
||||||
|
# devbox-rustup:
|
||||||
|
# devbox-cargo:
|
||||||
|
# devbox-vscode:
|
||||||
```
|
```
|
||||||
|
|
||||||
Docker Compose loads `.env` automatically from the same directory. All variables from `.env` are passed to the container via `env_file`. Do **not** hardcode provider settings in the `environment:` section — use `.env` instead.
|
Docker Compose loads `.env` automatically from the same directory. All variables from `.env` are passed to the container via `env_file`. Do **not** hardcode provider settings in the `environment:` section — use `.env` instead.
|
||||||
@@ -294,11 +428,11 @@ docker compose run --rm devbox bash # interactive shell
|
|||||||
|
|
||||||
### Base image (`latest`)
|
### Base image (`latest`)
|
||||||
|
|
||||||
- **Debian bookworm-slim** — glibc, full terminal/PTY support
|
- **Debian trixie-slim** — glibc, full terminal/PTY support
|
||||||
- **opencode** — AI coding assistant
|
- **opencode** — AI coding assistant
|
||||||
- **Node.js 22** — for npx-based MCP servers
|
- **Node.js 22** — for npx-based MCP servers
|
||||||
- **AWS CLI v2** — SSO and Bedrock authentication
|
- **AWS CLI v2** — SSO and Bedrock authentication
|
||||||
- **Dev tools** — git, git-lfs, ssh, ripgrep, fd, fzf, bat, eza, zoxide, jq, make, curl, wget, neovim 0.12, tmux, htop, tree
|
- **Dev tools** — git, git-lfs, ssh, ripgrep, fd, fzf, bat, eza, zoxide, uv, rustup, jq, make, curl, wget, neovim 0.12, tmux, htop, tree
|
||||||
- **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
|
- **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
|
||||||
|
|
||||||
### OMOS image (`latest-omos`)
|
### OMOS image (`latest-omos`)
|
||||||
|
|||||||
+19
-1
@@ -1,7 +1,7 @@
|
|||||||
# opencode-devbox — portable AI dev environment
|
# opencode-devbox — portable AI dev environment
|
||||||
# Debian-based container with opencode and configurable dev tools
|
# Debian-based container with opencode and configurable dev tools
|
||||||
|
|
||||||
ARG DEBIAN_VERSION=bookworm-slim
|
ARG DEBIAN_VERSION=trixie-slim
|
||||||
FROM debian:${DEBIAN_VERSION} AS base
|
FROM debian:${DEBIAN_VERSION} AS base
|
||||||
|
|
||||||
ARG TARGETARCH
|
ARG TARGETARCH
|
||||||
@@ -90,12 +90,30 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64"
|
|||||||
curl -fsSL "https://github.com/ajeetdsouza/zoxide/releases/download/v${ZOXIDE_VERSION}/zoxide-${ZOXIDE_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin zoxide && \
|
curl -fsSL "https://github.com/ajeetdsouza/zoxide/releases/download/v${ZOXIDE_VERSION}/zoxide-${ZOXIDE_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin zoxide && \
|
||||||
zoxide --version
|
zoxide --version
|
||||||
|
|
||||||
|
# uv — fast Python package manager (replaces pip, venv, pyenv)
|
||||||
|
ARG UV_VERSION=0.11.6
|
||||||
|
RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
|
||||||
|
curl -fsSL "https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/uv-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
|
||||||
|
install /tmp/uv-${ARCH}-unknown-linux-musl/uv /usr/local/bin/uv && \
|
||||||
|
install /tmp/uv-${ARCH}-unknown-linux-musl/uvx /usr/local/bin/uvx && \
|
||||||
|
rm -rf /tmp/uv-* && \
|
||||||
|
uv --version
|
||||||
|
|
||||||
|
# rustup — Rust toolchain manager
|
||||||
|
# Installs the rustup-init binary only. Users bootstrap Rust with:
|
||||||
|
# rustup-init -y && source ~/.cargo/env
|
||||||
|
# Toolchains persist via devbox-rustup and devbox-cargo volumes.
|
||||||
|
RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
|
||||||
|
curl -fsSL "https://static.rust-lang.org/rustup/dist/${ARCH}-unknown-linux-gnu/rustup-init" -o /usr/local/bin/rustup-init && \
|
||||||
|
chmod +x /usr/local/bin/rustup-init
|
||||||
|
|
||||||
# Set locale
|
# Set locale
|
||||||
RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
|
RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
|
||||||
ENV LANG=en_US.UTF-8
|
ENV LANG=en_US.UTF-8
|
||||||
ENV LANGUAGE=en_US:en
|
ENV LANGUAGE=en_US:en
|
||||||
ENV LC_ALL=en_US.UTF-8
|
ENV LC_ALL=en_US.UTF-8
|
||||||
ENV EDITOR=nvim
|
ENV EDITOR=nvim
|
||||||
|
ENV PATH="/home/developer/.local/bin:/home/developer/.cargo/bin:${PATH}"
|
||||||
|
|
||||||
# ── Node.js (required for opencode v1.x install + MCP servers) ──────
|
# ── Node.js (required for opencode v1.x install + MCP servers) ──────
|
||||||
ARG NODE_VERSION=22
|
ARG NODE_VERSION=22
|
||||||
|
|||||||
@@ -27,19 +27,33 @@ docker compose run --rm devbox
|
|||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Debian bookworm** base — glibc, full PTY/terminal support
|
- **Debian trixie** base — glibc, full PTY/terminal support
|
||||||
- **Configurable providers** — Anthropic, OpenAI, AWS Bedrock via env vars
|
- **Configurable providers** — Anthropic, OpenAI, AWS Bedrock via env vars
|
||||||
- **Host filesystem access** — bind mount any directory as `/workspace`
|
- **Host filesystem access** — bind mount any directory as `/workspace`
|
||||||
- **SSH key forwarding** — git push/pull to private repos
|
- **SSH key forwarding** — git push/pull to private repos
|
||||||
- **MCP server support** — Node.js included for `npx`-based MCP servers
|
- **MCP server support** — Node.js included for `npx`-based MCP servers
|
||||||
- **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
|
- **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
|
||||||
- **Optional runtimes** — Python, Go via build args (Node.js always included — required for opencode v1.x)
|
- **Python via uv** — `uv` package manager included; install Python on demand with `uv python install`
|
||||||
|
- **Rust via rustup** — `rustup-init` included; bootstrap Rust on demand with `rustup-init -y`
|
||||||
|
- **Optional runtimes** — Python (apt), Go via build args (Node.js always included — required for opencode v1.x)
|
||||||
- **Multi-agent orchestration** — optional [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) integration via build arg
|
- **Multi-agent orchestration** — optional [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) integration via build arg
|
||||||
- **AWS CLI v2** — built-in SSO/Bedrock authentication with headless device-code flow
|
- **AWS CLI v2** — built-in SSO/Bedrock authentication with headless device-code flow
|
||||||
- **Multi-arch** — amd64 and arm64
|
- **Multi-arch** — amd64 and arm64
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
Bind-mounted directories must exist on the host before starting the container. Docker creates missing directories as root-owned, which causes permission issues.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Required: workspace for your projects
|
||||||
|
mkdir -p ~/projects
|
||||||
|
|
||||||
|
# If mounting opencode config (recommended for persistent settings)
|
||||||
|
mkdir -p ~/.config/opencode
|
||||||
|
```
|
||||||
|
|
||||||
### Connecting to the container
|
### Connecting to the container
|
||||||
|
|
||||||
From your laptop, SSH into the remote server where Docker is running, then start the container:
|
From your laptop, SSH into the remote server where Docker is running, then start the container:
|
||||||
@@ -137,6 +151,119 @@ volumes:
|
|||||||
- ~/.config/nvim:/home/developer/.config/nvim:ro
|
- ~/.config/nvim:/home/developer/.config/nvim:ro
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Python development with uv
|
||||||
|
|
||||||
|
The image includes [uv](https://docs.astral.sh/uv/), a fast Python package manager that replaces pip, venv, and pyenv. Python is not pre-installed but can be installed on demand:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install Python (persists across restarts with devbox-uv volume)
|
||||||
|
uv python install 3.14
|
||||||
|
|
||||||
|
# Create a virtual environment and install dependencies
|
||||||
|
uv venv
|
||||||
|
uv pip install -r requirements.txt
|
||||||
|
|
||||||
|
# Or use uv's project workflow (reads pyproject.toml)
|
||||||
|
uv sync
|
||||||
|
|
||||||
|
# Run a Python script
|
||||||
|
uv run python script.py
|
||||||
|
|
||||||
|
# Install standalone Python tools
|
||||||
|
uvx ruff check .
|
||||||
|
```
|
||||||
|
|
||||||
|
Python installations are stored in `~/.local/share/uv/`. To persist them across container restarts, add the `devbox-uv` named volume to your `docker-compose.yml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
volumes:
|
||||||
|
- devbox-uv:/home/developer/.local/share/uv
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
devbox-uv:
|
||||||
|
```
|
||||||
|
|
||||||
|
Project virtual environments (`.venv`) are stored in your workspace directory and persist automatically via the `/workspace` bind mount.
|
||||||
|
|
||||||
|
### Rust development with rustup
|
||||||
|
|
||||||
|
The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# One-time setup: install Rust toolchain (~300MB, persists with volumes)
|
||||||
|
rustup-init -y
|
||||||
|
source ~/.cargo/env
|
||||||
|
|
||||||
|
# Now use Rust normally
|
||||||
|
cargo new my-project
|
||||||
|
cargo build
|
||||||
|
cargo run
|
||||||
|
```
|
||||||
|
|
||||||
|
To persist Rust toolchains and cargo data across container restarts, add named volumes to your `docker-compose.yml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
volumes:
|
||||||
|
- devbox-rustup:/home/developer/.rustup
|
||||||
|
- devbox-cargo:/home/developer/.cargo
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
devbox-rustup:
|
||||||
|
devbox-cargo:
|
||||||
|
```
|
||||||
|
|
||||||
|
### JavaScript and TypeScript
|
||||||
|
|
||||||
|
The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Initialize a new project
|
||||||
|
npm init -y
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
npm install
|
||||||
|
|
||||||
|
# Run TypeScript (via tsx, ts-node, etc.)
|
||||||
|
npx tsx src/index.ts
|
||||||
|
|
||||||
|
# Use npx for one-off tools
|
||||||
|
npx tsc --init
|
||||||
|
```
|
||||||
|
|
||||||
|
The OMOS image variant also includes **Bun**, a faster JavaScript runtime and package manager:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bun init
|
||||||
|
bun install
|
||||||
|
bun run src/index.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
Node modules are stored in your project directory under `/workspace` and persist automatically.
|
||||||
|
|
||||||
|
### VS Code integration
|
||||||
|
|
||||||
|
VS Code can connect directly to a running opencode-devbox container for a full IDE experience with IntelliSense, debugging, and extensions running inside the container.
|
||||||
|
|
||||||
|
**Local Docker (Docker running on your workstation):**
|
||||||
|
|
||||||
|
1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
|
||||||
|
2. Start the container: `docker compose up -d`
|
||||||
|
3. In VS Code: `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container" → select `opencode-devbox`
|
||||||
|
|
||||||
|
**Remote Docker (Docker running on a remote server, e.g. via SSH):**
|
||||||
|
|
||||||
|
1. Install the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extensions
|
||||||
|
2. Connect to the remote host: `Ctrl+Shift+P` → "Remote-SSH: Connect to Host"
|
||||||
|
3. On the remote host, start the container: `docker compose up -d`
|
||||||
|
4. In VS Code (now connected to the remote): `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container"
|
||||||
|
|
||||||
|
VS Code extensions installed inside the container persist as long as the container exists (not removed with `docker compose down`). For persistent extension storage across container recreations, add a named volume:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
volumes:
|
||||||
|
- devbox-vscode:/home/developer/.vscode-server
|
||||||
|
```
|
||||||
|
|
||||||
### Rebuilding the Image
|
### Rebuilding the Image
|
||||||
|
|
||||||
`docker compose run` and `docker compose up` use the existing image — they **do not rebuild** when you change the Dockerfile or build args (e.g. updating `OPENCODE_VERSION`). Rebuild explicitly:
|
`docker compose run` and `docker compose up` use the existing image — they **do not rebuild** when you change the Dockerfile or build args (e.g. updating `OPENCODE_VERSION`). Rebuild explicitly:
|
||||||
@@ -306,11 +433,11 @@ Host Machine
|
|||||||
├── ~/.aws ──bind mount──▶ /home/developer/.aws (Bedrock SSO)
|
├── ~/.aws ──bind mount──▶ /home/developer/.aws (Bedrock SSO)
|
||||||
└── .env ──env vars───▶ provider config + API keys
|
└── .env ──env vars───▶ provider config + API keys
|
||||||
|
|
||||||
Container (Debian bookworm)
|
Container (Debian trixie)
|
||||||
├── opencode binary
|
├── opencode binary
|
||||||
├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun)
|
├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun)
|
||||||
├── AWS CLI v2 (SSO + Bedrock auth)
|
├── AWS CLI v2 (SSO + Bedrock auth)
|
||||||
├── neovim 0.12, tmux, htop, bat, eza, zoxide, make
|
├── neovim 0.12, tmux, htop, bat, eza, zoxide, uv, rustup, make
|
||||||
├── git, ssh, ripgrep, fd, fzf, jq, curl, tree
|
├── git, ssh, ripgrep, fd, fzf, jq, curl, tree
|
||||||
├── Node.js (for MCP servers)
|
├── Node.js (for MCP servers)
|
||||||
├── Bun (optional — included with oh-my-opencode-slim)
|
├── Bun (optional — included with oh-my-opencode-slim)
|
||||||
@@ -326,6 +453,10 @@ Container (Debian bookworm)
|
|||||||
| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes | SSH keys |
|
| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes | SSH keys |
|
||||||
| `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes | AWS credentials/SSO cache |
|
| `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes | AWS credentials/SSO cache |
|
||||||
| `/home/developer/.local/share/opencode` | Named volume `devbox-data` | ✅ Yes | Session history, memory |
|
| `/home/developer/.local/share/opencode` | Named volume `devbox-data` | ✅ Yes | Session history, memory |
|
||||||
|
| `/home/developer/.local/share/uv` | Named volume `devbox-uv` (if configured) | ✅ Yes | Python installs, uv tool installs |
|
||||||
|
| `/home/developer/.rustup` | Named volume `devbox-rustup` (if configured) | ✅ Yes | Rust toolchains |
|
||||||
|
| `/home/developer/.cargo` | Named volume `devbox-cargo` (if configured) | ✅ Yes | Cargo binaries, registry cache |
|
||||||
|
| `/home/developer/.vscode-server` | Named volume `devbox-vscode` (if configured) | ✅ Yes | VS Code server and extensions |
|
||||||
| `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes | opencode.json, oh-my-opencode-slim.json, skills |
|
| `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes | opencode.json, oh-my-opencode-slim.json, skills |
|
||||||
|
|
||||||
**opencode config** (`opencode.json`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To persist config changes and use custom settings, mount the config directory from the host (see Custom opencode config above).
|
**opencode config** (`opencode.json`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To persist config changes and use custom settings, mount the config directory from the host (see Custom opencode config above).
|
||||||
|
|||||||
@@ -45,8 +45,24 @@ services:
|
|||||||
# Optional: persist opencode data (auth, memory, etc.)
|
# Optional: persist opencode data (auth, memory, etc.)
|
||||||
- devbox-data:/home/developer/.local/share/opencode
|
- devbox-data:/home/developer/.local/share/opencode
|
||||||
|
|
||||||
|
# Optional: persist uv data (Python installs, tool installs)
|
||||||
|
# Without this, 'uv python install' must be re-run after container removal.
|
||||||
|
- devbox-uv:/home/developer/.local/share/uv
|
||||||
|
|
||||||
|
# Optional: persist Rust toolchains and cargo data
|
||||||
|
# Without this, 'rustup-init' must be re-run after container removal.
|
||||||
|
# - devbox-rustup:/home/developer/.rustup
|
||||||
|
# - devbox-cargo:/home/developer/.cargo
|
||||||
|
|
||||||
|
# Optional: persist VS Code server and extensions across container recreations
|
||||||
|
# - devbox-vscode:/home/developer/.vscode-server
|
||||||
|
|
||||||
# Optional: AWS credentials/SSO config (not read-only — SSO writes token cache)
|
# Optional: AWS credentials/SSO config (not read-only — SSO writes token cache)
|
||||||
# - ~/.aws:/home/developer/.aws
|
# - ~/.aws:/home/developer/.aws
|
||||||
|
|
||||||
volumes:
|
volumes:
|
||||||
devbox-data:
|
devbox-data:
|
||||||
|
devbox-uv:
|
||||||
|
# devbox-rustup:
|
||||||
|
# devbox-cargo:
|
||||||
|
# devbox-vscode:
|
||||||
|
|||||||
+2
-1
@@ -48,7 +48,8 @@ EOF
|
|||||||
"provider": {
|
"provider": {
|
||||||
"amazon-bedrock": {
|
"amazon-bedrock": {
|
||||||
"options": {
|
"options": {
|
||||||
"region": "${AWS_REGION:-us-east-1}"
|
"region": "${AWS_REGION:-us-east-1}",
|
||||||
|
"profile": "${AWS_PROFILE:-default}"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -46,5 +46,24 @@ if [ -d "/home/$USER_NAME/.ssh" ] && [ "$(ls -A "/home/$USER_NAME/.ssh" 2>/dev/n
|
|||||||
fi
|
fi
|
||||||
fi
|
fi
|
||||||
|
|
||||||
|
# ── Fix ownership of named volume mount points ──────────────────────
|
||||||
|
# Named volumes are created as root on first use. Fix ownership so the
|
||||||
|
# developer user can write to them.
|
||||||
|
FINAL_UID="${TARGET_UID:-$CURRENT_UID}"
|
||||||
|
FINAL_GID="${TARGET_GID:-$CURRENT_GID}"
|
||||||
|
for dir in \
|
||||||
|
/home/"$USER_NAME"/.local/share/opencode \
|
||||||
|
/home/"$USER_NAME"/.local/share/uv \
|
||||||
|
/home/"$USER_NAME"/.rustup \
|
||||||
|
/home/"$USER_NAME"/.cargo \
|
||||||
|
/home/"$USER_NAME"/.vscode-server \
|
||||||
|
/home/"$USER_NAME"/.config/opencode \
|
||||||
|
/home/"$USER_NAME"/.config/nvim \
|
||||||
|
/home/"$USER_NAME"/.agents/skills; do
|
||||||
|
if [ -d "$dir" ] && [ "$(stat -c '%u' "$dir" 2>/dev/null)" != "$FINAL_UID" ]; then
|
||||||
|
chown -R "$FINAL_UID":"$FINAL_GID" "$dir" 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
# ── Drop to developer user for remaining setup ──────────────────────
|
# ── Drop to developer user for remaining setup ──────────────────────
|
||||||
exec gosu "$USER_NAME" /usr/local/bin/entrypoint-user.sh "$@"
|
exec gosu "$USER_NAME" /usr/local/bin/entrypoint-user.sh "$@"
|
||||||
|
|||||||
Reference in New Issue
Block a user