Skip to content

Dev Environment Runbook

Operational procedures for the dev LXC (131).

Redeploy

Trigger via Forgejo Actions (push to main touching relevant paths) or manual dispatch:

Forgejo > holo/chizuru-v2 > Actions > Deploy Dev > Run workflow

The workflow runs create-lxc.yml (idempotent) then dev.yml.

Update Claude Code CLI

SSH into the LXC and update globally:

ssh [email protected]
npm update -g @anthropic-ai/claude-code
claude --version

Or add the update to dev.yml and redeploy.

Update MCP Server Binaries

Go binaries (gitea-mcp, mcp-grafana)

  1. Check for new releases:
  2. gitea-mcp: https://gitea.com/gitea/gitea-mcp/releases
  3. mcp-grafana: https://github.com/grafana/mcp-grafana/releases
  4. Update the version vars in ansible/playbooks/dev.yml: 
    gitea_mcp_version: "v0.2.0"  # new version
mcp_grafana_version: "v0.5.0"  # new version
  5. Commit, push, redeploy.

Python MCP servers (proxmox-plus, mediabot)

These are installed via pip install -e . from cloned repos. To update:

ssh [email protected]

# proxmox-plus
cd /opt/mcp-servers/proxmox-plus
git pull
.venv/bin/pip install -e .

# mediabot
# Files are copied from chizuru-v2 repo — redeploy via workflow

Add a New Repo

ssh [email protected]
cd /opt/code-server/workspace
git clone https://claude:<token>@git.eva-00.network/holo/<repo>.git
cd <repo>
git config user.name "claude"
git config user.email "[email protected]"

To make it part of IaC, add the repo name to the forgejo_repos list in dev.yml.

Troubleshooting

code-server not loading

ssh [email protected]
docker ps -a  # check container status
docker logs code-server-dev
docker logs oauth2-proxy-code-server-dev

oauth2-proxy 500 error

Usually means the PocketID OIDC client is misconfigured or the cookie secret is wrong:

docker logs oauth2-proxy-code-server-dev 2>&1 | tail -20

Check Vault secrets match PocketID config: - Client ID and secret must match the OIDC client at auth.eva-00.network - Cookie secret must be exactly 16 raw characters - Redirect URL must be https://dev.eva-00.network/oauth2/callback

Claude Code MCP servers not connecting

ssh [email protected]

# Test forgejo MCP
/opt/mcp-servers/gitea-mcp -transport stdio -host https://git.eva-00.network -insecure

# Test grafana MCP
GRAFANA_URL=https://grafana.eva-00.network GRAFANA_SERVICE_ACCOUNT_TOKEN=<token> /opt/mcp-servers/mcp-grafana -transport stdio

# Check Claude config
cat /root/.claude/settings.json | python3 -m json.tool

Alloy not shipping logs

docker logs alloy 2>&1 | tail -20
# Check Loki is reachable
curl -s http://192.168.1.108:3100/ready

Backup and Restore

Verify backup

Check PBS for LXC 131 snapshots:

ssh [email protected]  # cajita-elite
proxmox-backup-client list --repository pbs-local

Or check via Proxmox UI: Datacenter > Storage > cajita-elite > Content > filter by 131.

Full restore from scratch

If the LXC is destroyed:

  1. Dispatch create-lxc workflow with target_lxc=dev
  2. Dispatch Deploy Dev workflow
  3. Re-clone any repos not in the forgejo_repos list
  4. Re-authenticate Claude Code CLI (claude will prompt for API key)

Restore from PBS backup

Via Proxmox UI: select PBS storage > find LXC 131 backup > Restore.

This restores everything: repos, VS Code config, Claude memory, MCP server configs.