# Development Environments — SNS Digital

**Entity:** SNS Digital · **Status:** Buildable now

## What it is

Reproducible dev environments that can be spun up on Proxmox in minutes.
No "works on my machine" — every project gets a defined environment.

## Stack

| Component | Software | FOSS | Role |
|-----------|----------|------|------|
| Remote dev | SSH + VS Code Remote / Kiro CLI | Yes | Code on server, UI on laptop |
| Environment definition | Ansible roles | Yes | Reproducible provisioning |
| Ephemeral VMs | Proxmox cloud-init clone | Yes | Fresh VM per project/experiment |
| Containers (app deps) | Docker Compose | Yes | Databases, caches, queues for local dev |
| Language management | mise (formerly rtx) | Yes | Python, Node, Go version pinning per project |

## Patterns

### Pattern 1: Remote VM (primary workflow)

```
Laptop (Kiro CLI / SSH)  ──────►  Dev VM on Proxmox
                                   ├── Project repo (git clone)
                                   ├── mise (.tool-versions)
                                   ├── Docker Compose (deps)
                                   └── Full Linux environment
```

**When:** Most development. Get a full Linux box with all tools, accessible
from any device over Tailscale/WireGuard.

**Build:**
1. Clone Debian 12 template on Proxmox.
2. Run `dev-workstation` Ansible role:
   - Install: git, mise, docker, docker-compose, build-essential
   - Configure: user `sam`, SSH key, dotfiles
   - Set resource: 4 vCPU, 8GB RAM, 64GB disk (adjustable)
3. SSH in, `mise install`, `docker compose up -d`, start coding.

### Pattern 2: Ephemeral project VM

**When:** Trying something risky, testing infrastructure changes, client-isolated work.

**Build:**
1. `qm clone 9000 --name experiment-xyz --full`
2. Work. Break things. Learn.
3. `qm destroy <vmid>` — gone, no cleanup.

### Pattern 3: Local laptop (lightweight)

**When:** Quick edits, offline work, documentation.

Just Kiro CLI + SSH config. The heavy lifting happens on the remote VM.

## mise Configuration (per-project)

```toml
# .mise.toml
[tools]
python = "3.12"
node = "20"
ansible = "latest"

[env]
VIRTUAL_ENV = ".venv"
```

Ensures every contributor (or future hire) gets the same versions without
polluting the system.

## Ansible Role: dev-workstation

```yaml
# roles/dev-workstation/tasks/main.yml (key tasks)
- name: Install base packages
  apt:
    name: [git, curl, jq, tmux, htop, build-essential, unzip]

- name: Install Docker
  # Official Docker repo, not distro package

- name: Install mise
  shell: curl https://mise.run | sh

- name: Clone dotfiles
  git:
    repo: gitea:sam/dotfiles.git
    dest: /home/sam/.dotfiles

- name: Symlink dotfiles
  # .bashrc, .tmux.conf, .gitconfig
```

## Security Posture

- **Dev VMs are not production.** They sit on the service VLAN but have no inbound
  ports open beyond SSH.
- **No secrets in dev environments.** Use `.env.example` + Vaultwarden lookups.
- **Ephemeral VMs destroyed after use.** No stale boxes accumulating.
- **Docker socket access** is the one elevated privilege — acceptable for dev, not prod.

## Upgrade Path

- **Devcontainers / Codespaces-like:** If you hire devs who need browser-based IDEs,
  deploy code-server or Gitpod self-hosted on Proxmox.
- **Nix flakes:** For truly reproducible environments beyond what mise offers
  (full system-level deps). Higher learning curve.
