diff --git a/docs/12-DEVELOPMENT-ENVIRONMENT.md b/docs/12-DEVELOPMENT-ENVIRONMENT.md new file mode 100644 index 0000000..9ec1887 --- /dev/null +++ b/docs/12-DEVELOPMENT-ENVIRONMENT.md @@ -0,0 +1,275 @@ +# Development Environment + +**Last Updated:** 2026-03-08 + +Web-based development environment running directly on Unraid, providing VS Code IDE with full host access to Claude Code, Cooperator CLI, Docker, and all project repositories. + +--- + +## OpenVSCode Server + +| Property | Value | +|----------|-------| +| **URL** | https://code.xtrm-lab.org | +| **Auth** | Authentik forward auth (SSO) | +| **Port** | 3100 (host-native, not a container) | +| **Binary** | `/mnt/user/appdata/openvscode/current/` (symlink) | +| **Config** | `/mnt/user/appdata/openvscode/config/` | +| **Boot Script** | `/mnt/user/appdata/openvscode/start.sh` | +| **Log** | `/mnt/user/appdata/openvscode/server.log` | + +**Why host-native?** Running directly on Unraid (not in a container) means the VS Code terminal has full access to `claude`, `cooperator`, `node`, `npm`, `docker`, `git`, and all host tools. No volume mount hacks or container-breaking updates. + +### Persistence + +All data lives on the array (`/mnt/user/`) — survives Unraid OS updates: + +| Component | Path | Purpose | +|-----------|------|---------| +| Server binary | `/mnt/user/appdata/openvscode/openvscode-server-v1.109.5-linux-x64/` | VS Code server | +| Symlink | `/mnt/user/appdata/openvscode/current` → version dir | Easy version switching | +| VS Code config | `/mnt/user/appdata/openvscode/config/` | Extensions, settings, themes | +| Start script | `/mnt/user/appdata/openvscode/start.sh` | Startup with PATH setup | + +### Updating OpenVSCode Server + +```bash +# Download new version +cd /mnt/user/appdata/openvscode +curl -fsSL "https://github.com/gitpod-io/openvscode-server/releases/download/openvscode-server-vX.Y.Z/openvscode-server-vX.Y.Z-linux-x64.tar.gz" -o new.tar.gz +tar xzf new.tar.gz && rm new.tar.gz + +# Switch symlink and restart +ln -sfn openvscode-server-vX.Y.Z-linux-x64 current +pkill -f "openvscode-server.*--port 3100" +/mnt/user/appdata/openvscode/start.sh +``` + +Extensions and settings are preserved (stored separately in `config/`). + +### Traefik Routing + +Defined in `/mnt/user/appdata/traefik/dynamic.yml`: + +```yaml +openvscode-secure: + rule: "Host(`code.xtrm-lab.org`)" + entryPoints: [https] + middlewares: [default-headers, authentik-forward-auth] + tls: + certResolver: cloudflare + service: openvscode + +# ... +openvscode: + loadBalancer: + servers: + - url: "http://192.168.10.20:3100" +``` + +--- + +## Claude Code + +| Property | Value | +|----------|-------| +| **Version** | 2.1.71 | +| **Binary** | `/mnt/user/appdata/claude-code/.npm-global/bin/claude` | +| **Symlink** | `/root/.local/bin/claude` | +| **Config** | `/mnt/user/appdata/claude-code/.claude.json` → `/root/.claude.json` | +| **Settings** | `/mnt/user/appdata/claude-code/.claude/` → `/root/.claude/` | +| **Boot Script** | `/mnt/user/appdata/claude-code/install-claude.sh` | + +### Persistence + +npm global prefix set to `/mnt/user/appdata/claude-code/.npm-global/` (array-backed). Boot script creates symlinks from `/root/` to persistent paths. + +### Updating Claude Code + +```bash +source /root/.bashrc +npm install -g @anthropic-ai/claude-code +claude --version +``` + +--- + +## Cooperator CLI + +| Property | Value | +|----------|-------| +| **Version** | 3.36.1 | +| **Binary** | `/mnt/user/appdata/claude-code/.npm-global/bin/cooperator` | +| **Config** | `~/.cooperator/.env` (Shortcut token, Confluence, git config) | +| **Registry** | `@ampeco:registry=https://gitlab.com/api/v4/projects/71775017/packages/npm/` | +| **npm auth** | `/root/.npmrc` (GitLab PAT) | + +### What Cooperator Install Sets Up + +- **Commands** — `~/.claude/commands/cooperator` → cooperator's claude-commands +- **Agents** — `~/.claude/agents/implementation-task-executor.md` +- **Skills** — 12 cooperator skills (shortcut-operations, create-feature-story, gitlab-operations, etc.) +- **Shortcut API** — validated via `~/.cooperator/.env` token + +### Updating Cooperator + +```bash +source /root/.bashrc +npm install -g @ampeco/cooperator +cooperator --version +``` + +**Note:** `/root/.npmrc` is in RAM — recreated on boot if needed. The GitLab PAT is stored in `/boot/config/go` would need a persistent `.npmrc` setup if token changes frequently. + +--- + +## GitLab CLI (glab) + +| Property | Value | +|----------|-------| +| **Version** | 1.89.0 | +| **Binary** | `/usr/local/bin/glab` (RAM — lost on reboot) | +| **Config** | `~/.config/glab-cli/config.yml` | +| **Auth** | GitLab PAT (same as npm registry token) | + +**Note:** glab binary at `/usr/local/bin/` is lost on Unraid reboot. Add to boot script or persist to appdata. + +--- + +## Python (via uv) + +| Property | Value | +|----------|-------| +| **uv** | `/root/.local/bin/uv` | +| **Python** | 3.12.13 (managed by uv) | +| **mikrotik-mcp venv** | `/mnt/user/projects/mikrotik-mcp/venv/` | +| **unraid-mcp venv** | `/mnt/user/projects/unraid-mcp/.venv/` | + +--- + +## Custom Skills + +6 custom skills synced from Mac to `/mnt/user/appdata/claude-code/custom-skills/`: + +| Skill | Description | +|-------|-------------| +| ev-compliance-story | EV regulatory compliance story creation | +| ev-protocol-expert | OCPP/OCPI/AFIR protocol expertise | +| frontend-designer | Nova/Vue component design | +| mikrotik-admin | MikroTik router management via MCP | +| prd-generator | Product requirements documents | +| unraid-admin | Unraid server management via MCP | + +Symlinked to `~/.claude/skills/` alongside 12 cooperator skills (18 total). + +--- + +## MCP Servers + +### Registered (TODO) + +The following MCP servers need to be registered via `claude mcp add` on Unraid: + +| Server | Command | Status | +|--------|---------|--------| +| **shortcut** | `node /mnt/user/appdata/claude-code/mcp-server-shortcut/dist/index.js` | Built, needs `claude mcp add` | +| **mikrotik** | `/mnt/user/projects/mikrotik-mcp/venv/bin/python -m mikrotik_mcp.server` | Venv ready, needs `claude mcp add` | +| **unraid** | `/mnt/user/projects/unraid-mcp/.venv/bin/python -m unraid_mcp.main` | Venv ready, needs `claude mcp add` | +| **playwright** | `npx -y @playwright/mcp@latest --isolated` | npx available, needs `claude mcp add` | +| **smartbear** | `npx -y @smartbear/mcp@latest` | npx available, needs `claude mcp add` | + +### Environment Variables for MCPs + +- **mikrotik**: `DEVICES_PATH=/mnt/user/projects/mikrotik-mcp/devices.json` +- **unraid**: `UNRAID_API_URL`, `UNRAID_API_KEY`, `UNRAID_MCP_TRANSPORT=stdio`, `UNRAID_VERIFY_SSL=false` +- **shortcut**: `SHORTCUT_API_TOKEN` (from `~/.cooperator/.env`) + +--- + +## Projects Workspace + +All projects at `/mnt/user/projects/`, opened as default folder in VS Code. + +### Personal Projects (Gitea) + +| Project | Gitea Repo | Description | +|---------|-----------|-------------| +| infrastructure | jazzymc/infrastructure | This repo — home lab documentation | +| claude-skills | jazzymc/claude-skills | Claude Code custom skills | +| mikrotik-mcp | jazzymc/mikrotik-mcp | MikroTik MCP server | +| unraid-mcp | jazzymc/unraid-mcp | Unraid MCP server | +| unraid-glass | jazzymc/unraid-glass | Unraid dashboard plugin | +| openclaw | jazzymc/openclaw | OpenClaw game project | +| nanobot-mcp | jazzymc/nanobot-mcp | Nanobot MCP server | +| nanobot-hkuds | jazzymc/nanobot-hkuds | Nanobot HKU DS | +| xtrm-agent | jazzymc/xtrm-agent | AI agent framework | +| geekmagic-smalltv | jazzymc/geekmagic-smalltv | SmallTV firmware | +| homarr | jazzymc/homarr | Homarr dashboard fork | +| shortcut-daily-sync | jazzymc/shortcut-daily-sync | Shortcut sync tool | + +**Remote URL format:** `https://jazzymc:@git.xtrm-lab.org/jazzymc/.git` + +### AMPECO Work Projects + +| Project | Source | Type | +|---------|--------|------| +| backend | GitLab (ampeco/apps/charge/backend) | Git clone | +| crm | GitLab (ampeco/apps/charge/crm) | Git clone | +| marketplace | GitLab (ampeco/apps/charge/marketplace) | Git clone | +| mobile-2 | GitLab (ampeco/apps/charge/mobile-2) | Git clone | +| ad-hoc-payment-web-app | GitLab (ampeco/apps/charge/external-apps/) | Git clone | +| dev-proxy | GitLab (ampeco/apps/shared/dev-proxy) | Git clone | +| ampeco-custom-dashboard-widgets-boilerplate | GitHub (ampeco/) | Git clone | +| docs | Local rsync | Reference docs | +| stories | Local rsync | Product stories | +| booking-ewa | Local rsync | Booking app | +| ewa-ui | Local rsync | EWA frontend | +| design-tokens | Local rsync | Design system tokens | +| ampeco-backup | Local rsync | Configuration backups | +| central_registry | Local rsync | Service registry | +| CCode-UI-Distribution-1.0.0 | Local rsync | UI distribution | +| automations | Local rsync | Automation scripts | + +**GitLab auth:** OAuth2 PAT in remote URLs. + +--- + +## Boot Sequence + +`/boot/config/go` triggers on Unraid boot: + +1. **Wait for array** — polls for `/mnt/user/appdata/claude-code` (up to 5 min) +2. **Claude Code setup** — `/mnt/user/appdata/claude-code/install-claude.sh` + - Creates symlinks (`/root/.local/bin/claude`, `/root/.claude`, `/root/.claude.json`) + - Writes `.bashrc` with persistent npm PATH +3. **OpenVSCode Server** — `/mnt/user/appdata/openvscode/start.sh` + - Kills any existing instance + - Starts on port 3100 with persistent config dir + - Sources Claude/Cooperator PATH for terminal sessions + +--- + +## Architecture Diagram + +``` +Browser → https://code.xtrm-lab.org + ↓ + Traefik (443) → Authentik SSO check + ↓ + OpenVSCode Server (:3100, host-native) + ↓ + Unraid Host Shell + ├── claude (2.1.71) + ├── cooperator (3.36.1) + ├── glab (1.89.0) + ├── node (22.18.0) / npm (10.9.3) / bun (1.3.10) + ├── uv + python 3.12 + ├── docker / docker compose + ├── git + └── /mnt/user/projects/ + ├── ampeco/ (18 AMPECO work projects) + ├── infrastructure/ + ├── claude-skills/ + ├── mikrotik-mcp/ + └── ... (12 personal repos) +``` diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 77da0d7..6d3b6fe 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -30,6 +30,48 @@ - **[DOCKER]** Fixed NetAlertX: added read_only, proper capabilities (NET_RAW/NET_ADMIN), and UID 20211 - **[DOCKER]** Removed empty netbox stack directory +## 2026-03-09 + +### Claude Code Tooling Completion +- **[SERVICE]** Installed Cooperator CLI v3.36.1 on Unraid (`npm install -g @ampeco/cooperator`) +- **[SERVICE]** Ran `cooperator install --non-interactive` — symlinked commands, agents, 12 skills to `~/.claude/` +- **[SERVICE]** Created `~/.cooperator/.env` with Shortcut API token, Confluence token, git config +- **[SERVICE]** Installed glab CLI v1.89.0 on Unraid (`/usr/local/bin/glab`) — authenticated as kaloyan.danchev +- **[SERVICE]** Installed uv package manager + Python 3.12.13 on Unraid +- **[SERVICE]** Created Python venvs for mikrotik-mcp and unraid-mcp projects +- **[SERVICE]** Copied MikroTik SSH key from Mac to Unraid — SSH to HAP ax3 verified working +- **[SERVICE]** Synced 6 custom Claude skills to `/mnt/user/appdata/claude-code/custom-skills/` (ev-compliance-story, ev-protocol-expert, frontend-designer, mikrotik-admin, prd-generator, unraid-admin) +- **[SERVICE]** Built shortcut MCP server at `/mnt/user/appdata/claude-code/mcp-server-shortcut/` +- **[SERVICE]** Enabled Claude plugins: ralph-loop, claude-md-management, playground +- **[DOCS]** Updated 12-DEVELOPMENT-ENVIRONMENT.md with Cooperator, glab, Python, skills, MCP sections + +#### TODO — MCP Server Registration +The following MCP servers are built/ready but need `claude mcp add` registration (requires interactive Claude session on Unraid): +- shortcut, mikrotik, unraid, playwright, smartbear + +## 2026-03-08 + +### Development Environment Setup +- **[SERVICE]** Installed OpenVSCode Server as host-native process (port 3100, not a container) — accessible at https://code.xtrm-lab.org +- **[SERVICE]** Traefik route added in dynamic.yml with Authentik forward auth +- **[SERVICE]** Boot auto-start via `/boot/config/go` → `/mnt/user/appdata/openvscode/start.sh` +- **[SERVICE]** Claude Code updated to v2.1.71, persistent at `/mnt/user/appdata/claude-code/.npm-global/` +- **[SERVICE]** Cooperator CLI v3.36.1 installed globally (`npm install -g @ampeco/cooperator`) +- **[SERVICE]** Created `/mnt/user/projects/` workspace with 12 personal repos (Gitea) + 18 AMPECO work projects (GitLab) +- **[DOCS]** Added `12-DEVELOPMENT-ENVIRONMENT.md` documenting full dev environment setup + +### Docker Maintenance +- **[DOCKER]** Created Unraid Docker Manager XML templates for 11 containers missing them (adguardhome, gitea, minecraft, ntfy, ollama, open-webui, etc.) +- **[DOCKER]** Pulled new images for all 30 active Dockge stacks, 14 containers received updates +- **[DOCKER]** Cleaned up dangling images: 10.95 GB reclaimed +- **[DOCKER]** Organized all 42 containers into Docker Folders (12 folders: Infrastructure, Security, Monitoring, DevOps, Media, etc.) +- **[DOCKER]** Pushed 6 local-only projects to Gitea (claude-skills, mikrotik-mcp, unraid-mcp, nanobot-mcp, nanobot-hkuds, openclaw) + +### Service Fixes +- **[FIX]** Gitea DB connection: fixed hardcoded PostgreSQL IP (172.18.0.13) → hostname `postgresql17` in compose and app.ini +- **[FIX]** Traefik: removed stale stopped container blocking restart +- **[FIX]** Redis: removed stale stopped container blocking recreate + ## 2026-02-26 ### WiFi & CAP VLAN Fixes