diff --git a/DOCKER_HUB.md b/DOCKER_HUB.md index e6fc59e..ac6a804 100644 --- a/DOCKER_HUB.md +++ b/DOCKER_HUB.md @@ -184,6 +184,7 @@ Understanding what survives container restarts and what doesn't: | `/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/.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/.config/opencode` | Host bind mount (if configured) | ✅ Yes — lives on host | opencode.json, oh-my-opencode-slim.json, skills | ### Key points @@ -191,6 +192,7 @@ Understanding what survives container restarts and what doesn't: - **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 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. - **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users). ## Custom opencode Config @@ -217,6 +219,39 @@ docker run -it --rm \ 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.12 + +# 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. + ## Using docker-compose Create a directory with a `docker-compose.yml` and a `.env` file: @@ -254,6 +289,8 @@ services: - ~/projects:/workspace - ~/.ssh:/home/developer/.ssh:ro - devbox-data:/home/developer/.local/share/opencode + # Optional: persist Python/uv installs across restarts + # - devbox-uv:/home/developer/.local/share/uv # Mount AWS config for Bedrock SSO (required for amazon-bedrock provider) # - ~/.aws:/home/developer/.aws # Optional: mount opencode config directory (persists config changes across restarts) @@ -265,6 +302,7 @@ services: volumes: devbox-data: + # devbox-uv: ``` 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. @@ -298,7 +336,7 @@ docker compose run --rm devbox bash # interactive shell - **opencode** — AI coding assistant - **Node.js 22** — for npx-based MCP servers - **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, 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) ### OMOS image (`latest-omos`) diff --git a/Dockerfile b/Dockerfile index 456f958..6299814 100644 --- a/Dockerfile +++ b/Dockerfile @@ -90,6 +90,15 @@ 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 && \ 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 + # Set locale RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen ENV LANG=en_US.UTF-8 diff --git a/README.md b/README.md index a418615..de76d6f 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,8 @@ docker compose run --rm devbox - **SSH key forwarding** — git push/pull to private repos - **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) -- **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` +- **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 - **AWS CLI v2** — built-in SSO/Bedrock authentication with headless device-code flow - **Multi-arch** — amd64 and arm64 @@ -137,6 +138,40 @@ volumes: - ~/.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.12 + +# 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. + ### 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: @@ -310,7 +345,7 @@ Container (Debian bookworm) ├── opencode binary ├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun) ├── AWS CLI v2 (SSO + Bedrock auth) -├── neovim 0.12, tmux, htop, bat, eza, zoxide, make +├── neovim 0.12, tmux, htop, bat, eza, zoxide, uv, make ├── git, ssh, ripgrep, fd, fzf, jq, curl, tree ├── Node.js (for MCP servers) ├── Bun (optional — included with oh-my-opencode-slim) @@ -326,6 +361,7 @@ Container (Debian bookworm) | `/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/.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/.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). diff --git a/docker-compose.yml b/docker-compose.yml index ca4e9d6..9f518bd 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -45,8 +45,13 @@ services: # Optional: persist opencode data (auth, memory, etc.) - 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: AWS credentials/SSO config (not read-only — SSO writes token cache) # - ~/.aws:/home/developer/.aws volumes: devbox-data: + devbox-uv: