hypervibed
This commit is contained in:
@@ -1,3 +1,139 @@
|
||||
# dockernecontainer
|
||||
# dockernecontainer (dnc)
|
||||
|
||||
Dockernecontainer is a helper for creating and managing virtual development environments.
|
||||
Containerized per-project development environments with TUI and GPU support.
|
||||
|
||||
## Dependencies
|
||||
|
||||
**Required**:
|
||||
- Linux with **rootful** Docker (≥20.10). Rootless Docker is detected and rejected.
|
||||
- Project directory you want to containerize
|
||||
|
||||
**GPU (choose what applies)**:
|
||||
- NVIDIA: `nvidia-smi` on PATH + `nvidia-container-toolkit` installed
|
||||
- Intel/AMD DRI: `/dev/dri` present on host (auto-detected)
|
||||
- AMD compute (KFD): `/dev/kfd` present on host (auto-detected)
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Create container from an image with your tools
|
||||
dnc setup --image ghcr.io/lstmnemodel/dnc-test-arch:latest
|
||||
|
||||
# Launch bundled kitty terminal (all tabs/splits exec into container)
|
||||
dnc
|
||||
|
||||
# Non-graphical fallback (useful for SSH sessions without display)
|
||||
dnc -- /bin/bash
|
||||
|
||||
# Run a command in container (non-interactive or interactive)
|
||||
dnc -- pacman -Syu
|
||||
|
||||
# Show container details
|
||||
dnc info
|
||||
|
||||
# List all containers
|
||||
dnc list
|
||||
|
||||
# Remove container
|
||||
dnc rm
|
||||
```
|
||||
|
||||
Each project directory gets its own container. A `.dnc` file in the project root tracks the container name. `dnc` walks up the directory tree to find it.
|
||||
|
||||
## How It Works
|
||||
|
||||
When you run `dnc` with no arguments:
|
||||
|
||||
1. **Finds your project**: Walks up from `$PWD` to find `.dnc` file
|
||||
2. **Extracts kitty config**: Copies `~/.config/kitty/` from INSIDE your project container
|
||||
3. **Launches kitty**: Bundled kitty terminal with config from container
|
||||
4. **Every new tab/window**: Automatically calls `docker exec -it` into your container
|
||||
|
||||
Kitty runs on your host (for GPU rendering and display), but every shell you open in it runs inside your project container via `docker exec`.
|
||||
|
||||
## What gets forwarded
|
||||
|
||||
| Category | What |
|
||||
|----------|------|
|
||||
| Network | `--network=host`, `--pid=host`, `--ipc=host` |
|
||||
| GPU | `--gpus all` (NVIDIA), `/dev/dri` bind-mount (Intel/AMD DRI), `/dev/kfd` (AMD compute) |
|
||||
| Runtime dirs | `/tmp`, `/run/user/$UID` (for clipboard, temp files) |
|
||||
| Git / SSH | SSH agent socket forwarded; `~/.ssh/`, `~/.gitconfig`, `~/.git-credentials` mounted at `/run/host/ssh`, `/run/host/gitconfig`, `/run/host/git-credentials` |
|
||||
| User config | `~/.config/dnc/` mounted read-write at `/run/host/config/` — images can read `dnc.toml` for colors, keybinds, IDE settings |
|
||||
| Shell history | Per-container history persists across rebuilds (`HISTFILE` set for bash/zsh, fish) |
|
||||
| nvim state | Per-container swap/undo persists across rebuilds (`~/.local/state/nvim`) |
|
||||
| Home | Fresh container home (not host bind-mount). Host home mounted read-only at `/run/host/home` |
|
||||
| Host env | All host environment variables dumped to `/run/host/env` (shell-sourceable) |
|
||||
| Project dir | Bind-mounted read-write at its host path |
|
||||
| Sudo | Installed automatically via `pacman`/`dnf`/`apt`/etc., NOPASSWD for the container user |
|
||||
|
||||
## Kitty Configuration
|
||||
|
||||
**Kitty config lives inside your project container**, not on the host:
|
||||
|
||||
```
|
||||
Inside container: ~/.config/kitty/kitty.conf
|
||||
```
|
||||
|
||||
This way:
|
||||
- Different projects can have different kitty configs
|
||||
- Config travels with your container image
|
||||
- New tabs automatically exec into your container (dnc overrides the `shell` directive)
|
||||
|
||||
If no config is found in the container, kitty runs with defaults plus the dnc exec wrapper.
|
||||
|
||||
## Extensibility via /run/host
|
||||
|
||||
dnc provides host data at well-known paths inside the container for optional integration:
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| `/run/host/home` | Read-only bind-mount of host `$HOME` |
|
||||
| `/run/host/env` | Shell-sourceable dump of all host environment variables |
|
||||
| `/run/host/config` | Read-write bind-mount of `~/.config/dnc/` — user IDE config |
|
||||
| `/run/host/ssh` | Read-only bind-mount of `~/.ssh/` |
|
||||
| `/run/host/gitconfig` | Read-only bind-mount of `~/.gitconfig` (if present) |
|
||||
| `/run/host/git-credentials` | Read-only bind-mount of `~/.git-credentials` (if present) |
|
||||
| `/run/host/kitty` | Read-only mount of bundled kitty bundle — provides `kitten` binary, terminfo, and `kitten run-shell` for shell integration |
|
||||
| `/run/host/state/history` | Per-container shell history (persists across rebuilds) |
|
||||
| `/run/host/state/nvim` | Per-container nvim swap/undo files (persists across rebuilds) |
|
||||
|
||||
### Config convention
|
||||
|
||||
Images are expected to read `/run/host/config/dnc.toml` (if present) to generate native config files for the IDE. This lets you swap images while keeping your colors, keybinds, and preferences — write once in TOML, use across any compliant image.
|
||||
|
||||
### Git / SSH
|
||||
|
||||
SSH agent socket is forwarded automatically via `$SSH_AUTH_SOCK`. Git operations (clone, push, pull) work inside the container without additional setup if your host has SSH keys loaded and `gitconfig` configured.
|
||||
|
||||
### Kitty shell integration
|
||||
|
||||
When `TERM=xterm-kitty` and the bundled kitty bundle is available, `entry.sh` automatically delegates to `kitten run-shell`. This gives you:
|
||||
|
||||
- Correct terminfo (`xterm-kitty`) — neovim and TUIs get true color, italics, styled underlines, cursor shapes
|
||||
- Shell integration — directory tracking in window title, clickable file paths, scroll marks
|
||||
- Clean shutdown — processes exit properly on window close (no warning dialog)
|
||||
|
||||
No image-side configuration needed. The fallback (when `TERM` is not `xterm-kitty` or the bundle is absent) launches the user's login shell directly.
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Rootful Docker only**: Rootless lacks the `--pid=host` capabilities dnc relies on.
|
||||
- **Container user = host uid**: UID 1:1 mapping (required for rootful Docker). The container user gets `NOPASSWD` sudo so package installs still work.
|
||||
- **No `--init` or systemd**: PID 1 is `init.sh`, not init/systemd. `systemctl` won't work.
|
||||
|
||||
## Commands
|
||||
|
||||
```
|
||||
dnc Launch kitty (bundled) with container context
|
||||
dnc -- Non-graphical interactive shell (docker exec)
|
||||
dnc -- <cmd> Run command in container
|
||||
dnc setup [--image IMG] Create container for this project
|
||||
dnc rm Remove container + .dnc
|
||||
dnc list List all dnc containers
|
||||
dnc info Show container details
|
||||
dnc web Show web IDE URL (if web_port set in .dnc)
|
||||
dnc agent [--opencode] [--cursor] Create DNC.md + agent rules
|
||||
dnc version Show version
|
||||
dnc help Show this help
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user