From 5f5db08ad4de8b19ff5d7e03298f56b40a1c1b80 Mon Sep 17 00:00:00 2001 From: Ian Date: Thu, 1 Oct 2026 23:23:01 +0200 Subject: [PATCH] chore: new README file --- README.md | 330 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 252 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 11b3f72..a90f1e2 100644 --- a/README.md +++ b/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 -- 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 +The host project directory and selected development caches/configuration directories are mounted into the container. -## 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 -~/dev/opencode-dev/ -├── opencode-config/ -├── opencode-data/ -├── opencode-cache/ -├── m2/ -├── npm-cache/ -├── pip-cache/ -├── certs/ -├── bash/ -└── projects/ -``` +## Files -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: - -```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: +By default, the host directory is: ```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 | -|---|---|---| -| `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 | +```bash +./dev.sh my-project --mount "$HOME/data:/data:ro" +``` -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.