ian/opencode-container
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: new README file

Browse Source
This commit is contained in:
Ian
2026-10-01 23:23:01 +02:00
parent 7b98d6dae6
commit 5f5db08ad4
1 changed files with 252 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+252 -78
View File
@@ -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.