From 34751e4013facd86181bb00a545d827dc655eb31 Mon Sep 17 00:00:00 2001
From: Timmy <loyangchun@gmail.com>
Date: Wed, 1 Apr 2026 17:32:13 +0800
Subject: [PATCH] docs: add CLAUDE.md for AI assistant context

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4bae1df
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,132 @@
+# 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