133 lines
3.7 KiB
Markdown
133 lines
3.7 KiB
Markdown
# 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
|