# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is a personal K3s Kubernetes cluster repository containing manifests and maintenance scripts for self-hosted services. The cluster runs on 3 nodes (vm120 master + vm121/vm122 workers) at 192.168.42.120.

### Quick Connection

```bash
ssh ubuntu@192.168.42.120
sudo -i
cd /root/k8s
```

### Git Workflow

1. Local edits happen in `/Users/timmy/42_120/k8s/`
2. Remote path on cluster: `/root/k8s`
3. Git repo: `http://192.168.42.124:31337/timmy/k3s.git`

After local changes:
```bash
git add -A && git commit -m "description" && git push
# Then on remote: git -C /root/k8s pull
```

## Architecture

### Ingress & Routing
- **Traefik** is the ingress controller
- Services exposed via Ingress with subdomains: `<service>.lotimmy.com`
- TLS is handled at the ingress level

### Storage
- **Longhorn** provides persistent storage
- PVCs use Longhorn storage class for data persistence
- PVCs are NOT deleted by `stop.sh` - data is preserved

### Naming Conventions
Manifests in each app's `manifests/` directory are prefixed with numbers for ordering:
- `00-*.yaml` - Middleware/config
- `01-*.yaml` - Secrets
- `02-*.yaml` - PVCs
- `03-*.yaml` - Database deployments
- `04-*.yaml` - Database services
- `05-*.yaml` - App deployments
- `06-*.yaml` - App services
- `07-*.yaml` - Ingress

## App Directory Structure

Each app in `apps/` follows this structure:
```
apps/<appname>/
├── manifests/          # Kubernetes YAML files
├── deploy.sh           # Apply manifests and wait for rollout
├── stop.sh             # Delete Deployment/Service/Ingress (keeps PVC/Secret)
├── status.sh           # Show pods, services, PVC, ingress status
├── backup.sh           # Backup data to local backup/ directory
├── restore.sh          # Restore from backup (if available)
└── backup/             # Local backups (gitignored)
```

## Common Commands

### Deploy an app
```bash
cd apps/<appname>/
./deploy.sh
```

### Check app status
```bash
cd apps/<appname>/
./status.sh
```

### Stop an app (preserves data)
```bash
cd apps/<appname>/
./stop.sh
```

### Cluster diagnostics
```bash
cd cluster/
./check_all.sh          # Run all diagnostics
./check_nodes.sh        # Node status
./check_storage.sh      # Longhorn volumes
./check_resources.sh    # Pod/Service/PVC summary
```

### Manual kubectl
```bash
kubectl get pods -A
kubectl get ingress -A
kubectl get pvc -A
kubectl logs -f <pod-name>
```

## Adding a New App

1. Copy the template: `cp -r apps/template apps/your-app`
2. Replace placeholders in manifests and scripts:
   - `{{APP_NAME}}` - app name
   - `{{IMAGE}}` - Docker image
   - `{{TAG}}` - version tag
   - `{{PORT}}` - container port
   - `{{HOST}}` - domain name
   - `{{SIZE}}` - storage size (e.g., 10Gi)
3. Make scripts executable: `chmod +x apps/your-app/*.sh`
4. Deploy: `cd apps/your-app && ./deploy.sh`

## Deployed Services

| App | Purpose | Ingress |
|-----|---------|---------|
| CodiMD | Markdown collaborative notes | codimd.lotimmy.com |
| Opengist | Git snippets management | opengist.lotimmy.com |
| Vaultwarden | Password manager | vaultwarden.lotimmy.com |
| Adminer | Database management tool | adminer.lotimmy.com |
| PostgreSQL | General database service | Cluster-internal only |

## Important Notes

- **Always run `status.sh` before making changes** to understand current state
- **PVCs are never deleted by `stop.sh`** - data persists across deployments
- **Secrets are stored in manifests** - these are committed to git (private repo)
- **Manifest ordering matters** - use number prefixes for correct apply order
- **Database apps** (like CodiMD) include both app and database deployments