# rdev Quick Reference

Quick reference for operating rdev on the k3s cluster.

## Prerequisites

```bash
# REQUIRED: Set kubeconfig before any kubectl command
export KUBECONFIG=~/.kube/orchard9-k3sf.yaml

# API access
export RDEV_API_URL="https://rdev.masq-ops.orchard9.ai"
export RDEV_API_KEY="<from rdev-credentials secret>"
```

## Essential Commands

### rdev API

```bash
# Health check
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/health

# List projects
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/projects

# Work queue stats
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/work/stats

# List credentials (masked)
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/credentials
```

### Pod Management

```bash
# View rdev pods
kubectl get pods -n rdev

# View logs (use script for convenience)
./scripts/logs.sh           # Last 100 lines
./scripts/logs.sh -f        # Follow/stream
./scripts/logs.sh -e        # Errors only

# Restart rdev-api
kubectl rollout restart deployment/rdev-api -n rdev
```

### Database Connections

#### CockroachDB

```bash
# Interactive SQL shell
kubectl exec -it -n databases cockroachdb-0 -- \
  /cockroach/cockroach sql --insecure --host=localhost:26257

# Run a query
kubectl exec -n databases cockroachdb-0 -- \
  /cockroach/cockroach sql --insecure --host=localhost:26257 \
  -e "SHOW DATABASES;"

# Check cluster status
kubectl exec -n databases cockroachdb-0 -- \
  /cockroach/cockroach node status --insecure --host=localhost:26257
```

**Console:** https://cockroachdb.threesix.ai

#### Redis

```bash
# Get password
REDIS_PASS=$(kubectl get secret -n threesix redis-credentials -o jsonpath="{.data.REDIS_PASSWORD}" | base64 -d)

# Interactive CLI
kubectl exec -it -n threesix redis-0 -- redis-cli -a "$REDIS_PASS"

# Ping test
kubectl exec -n threesix redis-0 -- redis-cli -a "$REDIS_PASS" ping

# Memory info
kubectl exec -n threesix redis-0 -- redis-cli -a "$REDIS_PASS" info memory
```

#### PostgreSQL (rdev metadata)

```bash
kubectl exec -it -n databases postgres-0 -- psql -U rdev -d rdev
```

### Credentials Management

Infrastructure credentials are stored in `.secrets` (gitignored) at repo root.

```bash
# Load credentials to database
./scripts/load-credentials.sh $RDEV_API_URL

# Verify loaded
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/credentials?category=cloudflare
```

**Key credential categories:**
- `gitea` - Git repository management
- `cloudflare` - DNS record management
- `woodpecker` - CI/CD pipelines

See [Credentials Guide](../.claude/guides/ops/credentials.md) for `.secrets` file format.

### Release & Deploy

```bash
# Release + deploy (one command)
./scripts/release.sh v0.10.1 "Description of changes" --deploy

# Release only (no deploy)
./scripts/release.sh v0.10.1 "Description of changes"

# Manual deploy
kubectl apply -f deployments/k8s/base/rdev-api.yaml
kubectl rollout restart -n rdev deployment/rdev-api
```

## Service URLs

| Service | Internal URL | External URL |
|---------|--------------|--------------|
| rdev API | `rdev-api.rdev.svc:8080` | https://rdev.masq-ops.orchard9.ai |
| CockroachDB | `cockroachdb-public.databases.svc:26257` | https://cockroachdb.threesix.ai |
| Redis | `redis.threesix.svc:6379` | (internal only) |
| PostgreSQL | `postgres.databases.svc:5432` | (internal only) |
| Gitea | `gitea.gitea.svc:3000` | https://git.threesix.ai |
| Woodpecker | `woodpecker-server.woodpecker.svc:8000` | https://ci.threesix.ai |

## Documentation Index

| Topic | Location |
|-------|----------|
| **Developer Guides** | `.claude/guides/` |
| Setup & Local Dev | `.claude/guides/local/setup.md` |
| Go Guidelines | `.claude/guides/backend/go-guidelines.md` |
| Hexagonal Architecture | `.claude/guides/backend/hexagonal.md` |
| **Operations** | `docs/operations/` |
| Deployment | `docs/operations/deployment.md` |
| Monitoring | `docs/operations/monitoring.md` |
| Troubleshooting | `docs/operations/troubleshooting.md` |
| Database Connections | `docs/operations/database-connections.md` |
| **API Reference** | `docs/api/` |
| Authentication | `docs/api/authentication.md` |
| SSE Streaming | `docs/api/sse-examples.md` |
| **Architecture** | `docs/architecture/` |
| Overview | `docs/architecture/README.md` |
| Security | `docs/architecture/security.md` |

## Troubleshooting

### rdev-api Not Responding

```bash
# Check pod status
kubectl get pods -n rdev -l app=rdev-api

# Check logs
./scripts/logs.sh -e  # errors only

# Restart
kubectl rollout restart deployment/rdev-api -n rdev
```

### Database Connection Issues

```bash
# Check CockroachDB
kubectl get pods -n databases -l app=cockroachdb

# Check Redis
kubectl get pods -n threesix -l app=redis

# Check PostgreSQL
kubectl get pods -n databases -l app=postgres
```

### Credentials Not Working

```bash
# Verify credentials loaded
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/credentials | jq

# Reload and restart
./scripts/load-credentials.sh $RDEV_API_URL
kubectl rollout restart deployment/rdev-api -n rdev
```

---

## Legacy: Claudebox VM Reference

> **Note:** This section documents the original claudebox Docker/VM deployment pattern.
> rdev now runs on k3s. See above for current commands.

The original architecture used Docker containers on a VM with Discord bot integration.
This reference is preserved for historical context and for deployments not using k3s.

<details>
<summary>Click to expand legacy claudebox documentation</summary>

### Architecture (VM-based)

```
Physical Layout:
├── Remote VM (Ubuntu 22.04+)
│   ├── Docker Container: claudebox-project-a
│   ├── Docker Container: claudebox-project-b
│   └── Docker Container: claudebox-project-c
│   └── Discord Bot Process (routes to containers)
```

### Key Differences from k3s

| Aspect | Claudebox (VM) | rdev (k3s) |
|--------|----------------|------------|
| Orchestration | Docker Compose | Kubernetes |
| Commands | `docker exec` | `kubectl exec` |
| Storage | Host volumes | Longhorn PVCs |
| Credentials | `~/.claude/.credentials.json` | PVC mount |
| Bot | Deno Discord bot | REST API |

### Claudebox Commands (VM)

```bash
# Start containers
cd ~/claude-infra
docker compose up -d

# View status
docker compose ps

# Execute command
docker exec -it claudebox-project-a bash

# Claude session
docker exec -it claudebox-project-a claude "your prompt"
```

### Management Script

```bash
claude-manage start              # Start all containers
claude-manage status             # Check system status
claude-manage logs project-a     # View logs
claude-manage shell project-b    # Open shell
claude-manage health             # Run health checks
```

For full claudebox documentation, see:
- https://github.com/RchGrav/claudebox
- https://github.com/zebbern/claude-code-discord

</details>