chore: new README file

Dockerfile

@@ -4,6 +4,7 @@ ARG UBUNTU_VERSION=26.04
 FROM ubuntu:${UBUNTU_VERSION}
 
 ARG NODE_VERSION=24.21.0
+ARG OPENCODE_VERSION=2.0.3
 
 ARG DEV_UID=1000
 ARG DEV_GID=1000
@@ -43,7 +44,6 @@ RUN apt-get update \
         python3-pip \
         python3-venv \
         ripgrep \
-        sudo \
         tar \
         tree \
         unzip \
@@ -67,9 +67,7 @@ RUN groupadd --gid "${DEV_GID}" dev \
         --uid "${DEV_UID}" \
         --gid "${DEV_GID}" \
         --create-home \
-        --shell /bin/bash dev \
+        --shell /bin/bash dev
-    && echo 'dev ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/dev \
-    && chmod 0440 /etc/sudoers.d/dev
 
 # Node.js + OpenCode
 RUN curl -fsSLO \
@@ -81,7 +79,7 @@ RUN curl -fsSLO \
     && rm "node-v${NODE_VERSION}-linux-x64.tar.xz" \
     && echo -n "node version: " && node --version \
     && echo -n "npm version: " && npm --version \
-    && npm install -g @opencode/cli \
+    && npm install -g "@opencode/cli@${OPENCODE_VERSION}" \
     && echo -n "opencode version: " && opencode --version \
     && npm cache clean --force
 

README.md

@@ -1,125 +1,299 @@
-# OpenCode Podman Dev Environment
+# OpenCode Development Container
 
-Podman-based Ubuntu 26.04 development container for OpenCode.
+This repository provides a Podman-based development container for running an AI coding agent in an isolated and reproducible environment.
 
-## Decisions
+The container includes common software development tools, Node.js, OpenCode, Python, Java, Maven, Git, Neovim, and other command-line utilities.
 
-- Ubuntu 26.04, amd64/x86_64
+The host project directory and selected development caches/configuration directories are mounted into the container.
-- OpenCode pinned to 1.18.32
-- Node.js 24.21.0 LTS, official Linux x64 binary
-- OpenJDK 11 + 17, Java 17 default
-- Python 3 from Ubuntu + pip + venv
-- Maven, no Gradle
-- Neovim installed with no custom configuration
-- non-root `dev` user
-- rootless Podman with `--userns=keep-id`
-- no Podman/Docker socket
-- no proxy configuration
-- SSH only for Git; host `.ssh` is read-only and host SSH agent is forwarded when available
-- host timezone and locale
-- custom CA certificates are host-mounted read-only and installed at runtime; invalid certs warn and do not stop startup
-- OpenCode config/data/cache and development caches persist on the host
-- Bash history is ephemeral
 
-## Host data
+## Requirements
 
-The scripts create automatically:
+* Linux
+* Podman
+* Bash
+* A working internet connection when building the image
+* CA certificates, if access to internal HTTPS services requires custom CAs
 
-```text
+## Files
-~/dev/opencode-dev/
-├── opencode-config/
-├── opencode-data/
-├── opencode-cache/
-├── m2/
-├── npm-cache/
-├── pip-cache/
-├── certs/
-├── bash/
-└── projects/
-```
 
-OpenCode stores provider credentials in `~/.local/share/opencode/auth.json`, which is therefore persisted by the `opencode-data` mount.
+* `Dockerfile` — builds the development image.
+* `build.sh` — builds or updates the image.
+* `dev.sh` — starts the development container.
+* `entrypoint.sh` — initializes the runtime environment.
 
-## Build
+## Build the image
+
+Run:
 
 ```bash
-chmod +x build.sh dev.sh opencode.sh
 ./build.sh
 ```
 
-Clean rebuild:
+The default image is:
+
+```text
+localhost/opencode-dev
+```
+
+The build uses the current host UID and GID for the `dev` user, so files created in mounted directories normally belong to the host user.
+
+### Build without cache
 
 ```bash
 ./build.sh --no-cache
 ```
 
-Intentional update rebuild:
+### Update the base image and Ubuntu packages
 
 ```bash
 ./build.sh --update
 ```
 
-## Shell
+### Show the build command without running it
+
+```bash
+./build.sh --dry-run
+```
+
+## Build arguments
+
+The following environment variables can be used to customize the image:
+
+```bash
+UBUNTU_VERSION=26.04
+NODE_VERSION=24.21.0
+OPENCODE_VERSION=2.0.3
+IMAGE_REPO=localhost/opencode-dev
+```
+
+For example:
+
+```bash
+NODE_VERSION=24.21.0 OPENCODE_VERSION=2.0.3 ./build.sh --no-cache
+```
+
+## Custom CA certificates
+
+Custom CA certificates must be placed in the repository `certs/` directory before building the image.
+
+Example:
+
+```text
+certs/
+├── company-root.crt
+└── company-intermediate.crt
+```
+
+The Dockerfile copies this directory to:
+
+```text
+/usr/local/share/ca-certificates
+```
+
+and runs:
+
+```bash
+update-ca-certificates
+```
+
+The resulting system CA bundle is also exposed through:
+
+```text
+NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
+```
+
+This allows both system tools and Node.js applications to trust the additional certificates.
+
+**Important:** CA certificates need to be present when the image is built. The runtime container does not install certificates from the host.
+
+## Run the container
+
+Run:
 
 ```bash
 ./dev.sh
 ```
 
-Start in a project:
+By default, the host directory is:
-
-```bash
-./dev.sh ~/dev/opencode-dev/projects/my-project
-```
-
-The same `projects` tree is mounted as `/workspace`.
-
-Optional additional mount:
-
-```bash
-./dev.sh ~/dev/opencode-dev/projects/my-project \
-  --mount "$HOME/another-project:/extra"
-```
-
-Put custom Bash settings in:
 
 ```text
-~/dev/opencode-dev/bash/bashrc
+$HOME/opencode-dev
 ```
 
-They are loaded after the image's normal Bash environment. History remains ephemeral.
+and projects are stored in:
 
-## OpenCode
+```text
+$HOME/opencode-dev/projects
+```
+
+The container starts in `/workspace`.
+
+To start in a specific project:
 
 ```bash
-./opencode.sh
+./dev.sh my-project
 ```
 
-Or start in a project:
+or:
 
 ```bash
-./opencode.sh ~/dev/opencode-dev/projects/my-project
+./dev.sh /path/to/opencode-dev/projects/my-project
 ```
 
-Arguments are forwarded to OpenCode:
+Absolute paths outside the projects directory are not accepted as the initial working directory.
+
+## Mounted directories
+
+The following host directories are mounted into the container:
+
+| Host               | Container                         | Purpose                          |
+| ------------------ | --------------------------------- | -------------------------------- |
+| `projects/`        | `/workspace`                      | Source code                      |
+| `opencode-config/` | `/home/dev/.config/opencode`      | OpenCode configuration           |
+| `opencode-data/`   | `/home/dev/.local/share/opencode` | OpenCode persistent data         |
+| `opencode-cache/`  | `/home/dev/.cache/opencode`       | OpenCode cache                   |
+| `m2/`              | `/home/dev/.m2`                   | Maven cache                      |
+| `npm-cache/`       | `/home/dev/.npm`                  | npm cache                        |
+| `pip-cache/`       | `/home/dev/.cache/pip`            | pip cache                        |
+| `bash/`            | `/host-bash`                      | Host-provided Bash configuration |
+| `$HOME/.gitconfig` | `/home/dev/.gitconfig`            | Git configuration                |
+
+All standard development directories are created automatically by `dev.sh`.
+
+## Additional mounts
+
+Additional host directories can be mounted with `--mount`.
+
+Example:
 
 ```bash
-./opencode.sh ~/dev/opencode-dev/projects/my-project --help
+./dev.sh my-project --mount "$HOME/other:/extra"
 ```
 
-## Persistent mounts
+Read-only mounts are also supported:
 
-| Host | Container | Mode |
+```bash
-|---|---|---|
+./dev.sh my-project --mount "$HOME/data:/data:ro"
-| `opencode-config` | `~/.config/opencode` | RW |
+```
-| `opencode-data` | `~/.local/share/opencode` | RW |
-| `opencode-cache` | `~/.cache/opencode` | RW |
-| `m2` | `~/.m2` | RW |
-| `npm-cache` | `~/.npm` | RW |
-| `pip-cache` | `~/.cache/pip` | RW |
-| `certs` | `/host-certs` | RO |
-| `~/.gitconfig` | `~/.gitconfig` | RO |
-| `~/.ssh` | `~/.ssh` | RO |
-| `bash` | `/host-bash` | RO |
-| `projects` | `/workspace` | RW |
 
-No credentials or personal OpenCode state are baked into the image.
+Multiple mounts can be specified:
+
+```bash
+./dev.sh my-project \
+  --mount "$HOME/data:/data:ro" \
+  --mount "$HOME/tools:/tools:rw"
+```
+
+## Environment variables
+
+The main runtime paths can be customized:
+
+```bash
+OPENCODE_DEV_HOME
+PROJECT_DIR
+OPENCODE_CONFIG
+OPENCODE_SHARE_DATA
+OPENCODE_CACHE
+M2_FOLDER
+NPM_CACHE
+PIP_CACHE
+BASH_FOLDER
+IMAGE_REPO
+```
+
+Example:
+
+```bash
+OPENCODE_DEV_HOME="$HOME/my-opencode" ./dev.sh
+```
+
+## Git configuration
+
+The host Git configuration is mounted read-only:
+
+```text
+$HOME/.gitconfig -> /home/dev/.gitconfig
+```
+
+If the file does not exist, the script prints a warning and Git uses the container defaults.
+
+SSH configuration and SSH agent forwarding are currently disabled in the script. They can be enabled by uncommenting the corresponding sections in `dev.sh`.
+
+## Security
+
+The container runs with several restrictions:
+
+* Runs as the `dev` user.
+* Uses the host UID/GID.
+* Drops all Linux capabilities.
+* Uses `no-new-privileges`.
+* Uses a temporary container (`--rm`).
+* Does not run as root.
+* Uses the default Podman network.
+
+The project directory is mounted read/write because the AI agent needs to create and modify source files.
+
+## Locale
+
+The host locale is passed to the container through:
+
+```text
+HOST_LANG
+HOST_LC_ALL
+```
+
+The entrypoint generates the requested UTF-8 locale when necessary.
+
+For example, the host locale is automatically passed when running:
+
+```bash
+./dev.sh
+```
+
+## Typical workflow
+
+Build the image:
+
+```bash
+./build.sh
+```
+
+Start the development environment:
+
+```bash
+./dev.sh
+```
+
+Or start directly in a project:
+
+```bash
+./dev.sh my-project
+```
+
+Inside the container, the project is available under:
+
+```bash
+/workspace
+```
+
+OpenCode can then be started normally:
+
+```bash
+opencode
+```
+
+The container is removed when the shell exits, while source code, OpenCode data, configuration, and development caches remain on the host.
+
+## Customization
+
+Most image versions are defined at the top of the `Dockerfile`:
+
+```dockerfile
+ARG UBUNTU_VERSION=26.04
+ARG NODE_VERSION=24.21.0
+ARG OPENCODE_VERSION=2.0.3
+```
+
+Runtime paths and container options are defined in `dev.sh`.
+
+This separation allows the image to contain the stable development environment while projects, configuration, caches, and other working data remain outside the container.

build.sh

@@ -6,7 +6,8 @@ cd "$SCRIPT_DIR"
 
 UBUNTU_VERSION="${UBUNTU_VERSION:-26.04}"
 # OPENCODE_VERSION=$(curl -fsSI https://github.com/anomalyco/opencode/releases/latest | sed -n 's/^location:.*\/tag\/v\{0,1\}\(.*\)\r$/\1/ip')
-NODE_VERSION=$(curl -fsSL https://nodejs.org/dist/index.json | sed -n 's/.*"version":"v\([^"]*\)".*"lts":".*".*/\1/p' | head -n 1)
+NODE_VERSION="${NODE_VERSION:-24.21.0}"
+OPENCODE_VERSION="${OPENCODE_VERSION:-2.0.3}"
 
 IMAGE_REPO="${IMAGE_REPO:-localhost/opencode-dev}"
 # IMAGE_TAG="${IMAGE_TAG:-${OPENCODE_VERSION}}"
@@ -49,6 +50,7 @@ if [ ${DRY_RUN} == false ]; then
     "${NO_CACHE[@]}" \
     --build-arg "UBUNTU_VERSION=${UBUNTU_VERSION}" \
     --build-arg "NODE_VERSION=${NODE_VERSION}" \
+    --build-arg "OPENCODE_VERSION=${OPENCODE_VERSION}" \
     --build-arg "DEV_UID=${DEV_UID}" \
     --build-arg "DEV_GID=${DEV_GID}" \
     -t "$IMAGE" \

dev.sh

@@ -18,7 +18,6 @@ M2_FOLDER="${M2_FOLDER:-$BASE_DIR/m2}"
 NPM_MODULES="${NPM_MODULES:-$BASE_DIR/npm-modules}"
 NPM_CACHE="${NPM_CACHE:-$BASE_DIR/npm-cache}"
 PIP_CACHE="${PIP_CACHE:-$BASE_DIR/pip-cache}"
-CERTIFICATES="${CERTIFICATES:-$BASE_DIR/certs}"
 BASH_FOLDER="${BASH_FOLDER:-$BASE_DIR/bash}"
 
 mkdir -p \
@@ -31,7 +30,6 @@ mkdir -p \
     "$NPM_MODULES" \
     "$NPM_CACHE" \
     "$PIP_CACHE" \
-    "$CERTIFICATES" \
     "$BASH_FOLDER"
 
 if [[ ! -f "$HOME/.gitconfig" ]]; then
@@ -63,7 +61,6 @@ if [[ ! -d "$PROJECTS_DIR" ]]; then
   exit 1
 fi
 
-# --security-opt=no-new-privileges
 ARGS=(
   run --rm -it
   --name opencode-dev
@@ -71,6 +68,10 @@ ARGS=(
   --userns=keep-id
   --network=default
   --tz=local
+
+  --security-opt=no-new-privileges
+  --cap-drop=ALL
+
   -e "HOST_LANG=${LANG:-C.UTF-8}"
   -e "HOST_LC_ALL=${LC_ALL:-}"
   -e "START_DIR=${START_DIR}"
@@ -81,7 +82,6 @@ ARGS=(
   -v "$M2_FOLDER:/home/dev/.m2:rw"
   -v "$NPM_CACHE:/home/dev/.npm:rw"
   -v "$PIP_CACHE:/home/dev/.cache/pip:rw"
-  -v "$CERTIFICATES:/host-certs:ro"
   -v "$PROJECTS_DIR:/workspace:rw"
   -v "$HOME/.gitconfig:/home/dev/.gitconfig:ro"
   # -v "$HOME/.ssh:/home/dev/.ssh:ro"

entrypoint.sh

@@ -1,29 +1,29 @@
 #!/bin/bash
 set -euo pipefail
 
-CERT_DIR="${CERT_DIR:-/host-certs}"
+# CERT_DIR="${CERT_DIR:-/host-certs}"
-
+#
-if [[ -d "$CERT_DIR" ]]; then
+# if [[ -d "$CERT_DIR" ]]; then
-  shopt -s nullglob
+#   shopt -s nullglob
-  certs=("$CERT_DIR"/*.crt "$CERT_DIR"/*.pem)
+#   certs=("$CERT_DIR"/*.crt "$CERT_DIR"/*.pem)
-  if ((${#certs[@]})); then
+#   if ((${#certs[@]})); then
-    mkdir -p /usr/local/share/ca-certificates/opencode-host
+#     mkdir -p /usr/local/share/ca-certificates/opencode-host
-    for cert in "${certs[@]}"; do
+#     for cert in "${certs[@]}"; do
-      target="/usr/local/share/ca-certificates/opencode-host/$(basename "${cert%.*}").crt"
+#       target="/usr/local/share/ca-certificates/opencode-host/$(basename "${cert%.*}").crt"
-      if openssl x509 -in "$cert" -noout >/dev/null 2>&1; then
+#       if openssl x509 -in "$cert" -noout >/dev/null 2>&1; then
-        cp -f "$cert" "$target"
+#         cp -f "$cert" "$target"
-      else
+#       else
-        echo "WARNING: ignoring invalid CA certificate: $cert" >&2
+#         echo "WARNING: ignoring invalid CA certificate: $cert" >&2
-      fi
+#       fi
-    done
+#     done
-    if update-ca-certificates >/tmp/opencode-ca.log 2>&1; then
+#     if update-ca-certificates >/tmp/opencode-ca.log 2>&1; then
-      :
+#       :
-    else
+#     else
-      echo "WARNING: update-ca-certificates failed; continuing." >&2
+#       echo "WARNING: update-ca-certificates failed; continuing." >&2
-      cat /tmp/opencode-ca.log >&2 || true
+#       cat /tmp/opencode-ca.log >&2 || true
-    fi
+#     fi
-  fi
+#   fi
-fi
+# fi
 
 host_lang="${HOST_LANG:-${LANG:-C.UTF-8}}"
 host_lc_all="${HOST_LC_ALL:-${LC_ALL:-}}"