26595b724f
Embed and build @probo/compliance-portal for the /trust path and custom-domain SPA so production ships the v2 portal. Keep apps/trust in the repo for local use on port 5175; portal takes 5174. Signed-off-by: Émile Ré <emile@probo.com>
90 lines
2.9 KiB
Markdown
90 lines
2.9 KiB
Markdown
# Lima Sandbox Environments
|
|
|
|
Run isolated dev environments using [Lima](https://lima-vm.io/) VMs. Each git
|
|
worktree gets its own VM with Docker, standard ports, and a unique IP — no port
|
|
conflicts between sandboxes.
|
|
|
|
## Prerequisites
|
|
|
|
```bash
|
|
brew install lima jq
|
|
```
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# Create and start a sandbox for the current worktree
|
|
./contrib/lima/sandbox.sh create
|
|
|
|
# Check status and get the VM IP
|
|
./contrib/lima/sandbox.sh status
|
|
|
|
# Build the backend binary (probo-stack starts automatically on boot)
|
|
./contrib/lima/sandbox.sh exec -- make build
|
|
|
|
# Start probod, the console, and the compliance-portal dev servers
|
|
./contrib/lima/sandbox.sh exec -- sudo systemctl start probod probo-console probo-compliance-portal
|
|
|
|
# Access services from your host browser using the VM IP
|
|
# e.g. http://192.168.105.2:5173 (console)
|
|
# e.g. http://192.168.105.2:5174 (compliance-portal)
|
|
# e.g. http://192.168.105.2:8080 (API)
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `./contrib/lima/sandbox.sh create [--cpus C] [--memory M] [--disk D]` | Create and start a new VM |
|
|
| `./contrib/lima/sandbox.sh start` | Start a stopped VM |
|
|
| `./contrib/lima/sandbox.sh stop` | Shut down the VM (preserves disk and Docker images) |
|
|
| `./contrib/lima/sandbox.sh restart` | Stop + start |
|
|
| `./contrib/lima/sandbox.sh delete` | Remove the VM entirely |
|
|
| `./contrib/lima/sandbox.sh ssh` | Interactive shell at `/workspace` |
|
|
| `./contrib/lima/sandbox.sh exec -- CMD` | Run a command in the VM |
|
|
| `./contrib/lima/sandbox.sh status` | Show VM state, IP, and service URLs |
|
|
| `./contrib/lima/sandbox.sh list` | List all `probo-*` VMs |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Host (macOS)
|
|
├── worktree: ~/Developer/probo/delhi → VM "probo-delhi" (192.168.105.x)
|
|
├── worktree: ~/Developer/probo/feature-a → VM "probo-feature-a" (192.168.105.y)
|
|
└── worktree: ~/Developer/probo/feature-b → VM "probo-feature-b" (192.168.105.z)
|
|
```
|
|
|
|
Each VM:
|
|
- Mounts the worktree at `/workspace` via virtiofs (read-write)
|
|
- Runs Docker + docker-compose inside the VM
|
|
- Forwards the host SSH agent
|
|
- Gets its own IP via vzNAT — all services on standard ports
|
|
|
|
## Makefile targets
|
|
|
|
Convenience wrappers are available:
|
|
|
|
```bash
|
|
make sandbox-create
|
|
make sandbox-start
|
|
make sandbox-stop
|
|
make sandbox-delete
|
|
make sandbox-ssh
|
|
make sandbox-status
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**VM won't start**: Check `limactl list` for stale entries. Delete with
|
|
`./contrib/lima/sandbox.sh delete` and recreate.
|
|
|
|
**Slow file I/O**: The worktree is mounted via virtiofs which is fast for most
|
|
operations. If `node_modules` is slow, consider symlinking it to VM-local disk.
|
|
|
|
**Docker permission denied**: The provision script adds the lima user to the
|
|
docker group. If you see permission errors, restart the VM with
|
|
`./contrib/lima/sandbox.sh restart`.
|
|
|
|
**Can't reach VM IP from host**: Ensure vzNAT networking is working. Run
|
|
`./contrib/lima/sandbox.sh status` to verify the IP is assigned.
|