Streamline AI docs, add skills, enforce symlink-everything policy
- Add .claude/skills/: homelab-context (auto-loads key facts each session), homelab-status (/homelab-status command), deploy-config (symlink setup guide) - Remove AGENTS.md and ai/sessions/: superseded by plan mode + skill system - Remove 4 obsolete session commands (session-start/list/switch, reload-instructions) - Rewrite CLAUDE.md: remove duplicate content, enforce symlink policy, clarify sudo pattern - Trim docs/services.md from 946 to ~230 lines: remove planning-era content, keep install steps and current status for migration reference - Strip stale "sudo cp" deploy header from ssh-honeypot.service (now symlinked to repo) - Update TODO.md: mark NAS migration and symlink tasks done, add jellyfin upgrade warning
This commit is contained in:
52
.claude/skills/deploy-config/SKILL.md
Normal file
52
.claude/skills/deploy-config/SKILL.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: deploy-config
|
||||
description: Set up symlinks from system config locations to this repo. Use when setting up on a new machine, or when a config file is found to be a real file instead of a symlink (config drift). Not for routine config changes — just edit the repo file directly.
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Write, Bash(chmod *), Bash(diff *), Bash(ls *)
|
||||
---
|
||||
|
||||
All system configs should be symlinked to this repo. Editing the repo file IS editing the live config.
|
||||
|
||||
## Symlink Map
|
||||
|
||||
| System location | Repo source |
|
||||
|---|---|
|
||||
| `/etc/nginx/sites-available/homelab` | `config/nginx/homelab.conf` |
|
||||
| `/var/www/homelab/index.html` | `config/www/index.html` |
|
||||
| `/etc/systemd/system/copyparty.service` | `config/systemd/copyparty.service` |
|
||||
| `/etc/systemd/system/glances-web.service` | `config/systemd/glances-web.service` |
|
||||
| `/etc/systemd/system/ssh-honeypot.service` | `config/systemd/ssh-honeypot.service` |
|
||||
| `/opt/docker/<service>/docker-compose.yml` | `config/docker/<service>/docker-compose.yml` |
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- **New machine setup**: Create all symlinks from scratch
|
||||
- **Drift detected**: A system file is a real file instead of a symlink — replace it with a symlink
|
||||
- **New config added to repo**: Create the initial symlink for it
|
||||
|
||||
## How to create/fix a symlink
|
||||
|
||||
Generate a script in `scripts/tmp/symlink-<name>.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
REPO="/home/hoborg/homelab/<repo-path>"
|
||||
SYSTEM="<system-path>"
|
||||
|
||||
# Back up if it's a real file (not already a symlink)
|
||||
[ ! -L "$SYSTEM" ] && cp "$SYSTEM" "${SYSTEM}.backup.$(date +%Y%m%d)" && echo "Backup created"
|
||||
|
||||
ln -sf "$REPO" "$SYSTEM" && echo "Symlink created"
|
||||
# Add post-link steps here (e.g. nginx -t && systemctl reload nginx, systemctl daemon-reload)
|
||||
```
|
||||
|
||||
Tell the user to run: `sudo bash ~/homelab/scripts/tmp/symlink-<name>.sh`
|
||||
|
||||
## Routine config changes
|
||||
|
||||
Just edit `config/<path>` in the repo. The symlink means it's already live. Then:
|
||||
- Nginx: `sudo nginx -t && sudo systemctl reload nginx`
|
||||
- Systemd unit: `sudo systemctl daemon-reload && sudo systemctl restart <service>`
|
||||
- Docker: `cd /opt/docker/<service> && docker compose restart`
|
||||
- www/index.html: no action needed (served directly)
|
||||
98
.claude/skills/homelab-context/SKILL.md
Normal file
98
.claude/skills/homelab-context/SKILL.md
Normal file
@@ -0,0 +1,98 @@
|
||||
---
|
||||
name: homelab-context
|
||||
description: Background reference for the homelab repo. Auto-loads key facts about services, ports, paths, and operational rules when working in this project.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Domain**: ak-homelab.duckdns.org (DuckDNS)
|
||||
- **Static IP**: 192.168.0.100 (interface: enp4s0)
|
||||
- **SSH**: port 2222 (system), port 2223 (Gitea git)
|
||||
- **NAS**: 192.168.0.101, mounted at `/mnt/nas/`
|
||||
|
||||
## Services & Ports
|
||||
|
||||
| Service | Port | Type | Path |
|
||||
|-------------|-------|----------|-----------------|
|
||||
| Nginx | 80/443| systemd | reverse proxy |
|
||||
| Gitea | 3000 | Docker | /gitea/ |
|
||||
| Jellyfin | 8096 | Docker | /media/ |
|
||||
| Copyparty | 8082 | systemd | /files/ |
|
||||
| Netdata | 19999 | Docker | /netdata/ |
|
||||
| Portainer | 9000 | Docker | /portainer/ |
|
||||
| qBittorrent | 8080 | Docker | /qbt/ |
|
||||
|
||||
## Key Paths
|
||||
|
||||
All configs are **symlinked** from system locations to this repo — editing the repo file is editing the live config:
|
||||
|
||||
| System location | Repo source |
|
||||
|---|---|
|
||||
| `/opt/docker/<service>/docker-compose.yml` | `config/docker/<service>/docker-compose.yml` |
|
||||
| `/etc/nginx/sites-available/homelab` | `config/nginx/homelab.conf` |
|
||||
| `/var/www/homelab/index.html` | `config/www/index.html` |
|
||||
| `/etc/systemd/system/copyparty.service` | `config/systemd/copyparty.service` |
|
||||
| `/etc/systemd/system/glances-web.service` | `config/systemd/glances-web.service` |
|
||||
| `/etc/systemd/system/ssh-honeypot.service` | `config/systemd/ssh-honeypot.service` |
|
||||
|
||||
- NAS docker data: `/mnt/nas/docker-data/<service>/`
|
||||
|
||||
## Critical Rules
|
||||
|
||||
### Docker UID for NAS-mounted volumes
|
||||
Services with data on NAS (`/mnt/nas/`) must use `USER_UID=1024 USER_GID=100` to match NAS file ownership. Services with local storage use `1000:1000`.
|
||||
|
||||
### Docker config changes
|
||||
Edit `config/docker/<service>/docker-compose.yml` in repo → restart container. No copy needed (symlinked).
|
||||
|
||||
### After editing a config in repo
|
||||
- **Docker**: `cd /opt/docker/<service> && docker compose restart`
|
||||
- **Nginx**: `sudo nginx -t && sudo systemctl reload nginx`
|
||||
- **Systemd unit**: `sudo systemctl daemon-reload && sudo systemctl restart <service>`
|
||||
- **www/index.html**: no action needed
|
||||
|
||||
### Sudo scripts
|
||||
Never run sudo directly. Generate a script in `scripts/tmp/` and run `sudo bash ~/homelab/scripts/tmp/<script>.sh`.
|
||||
The sudoers rule `/etc/sudoers.d/homelab-scripts` grants NOPASSWD for `scripts/tmp/*` — no password needed.
|
||||
|
||||
### s6-overlay containers (Gitea)
|
||||
Do NOT set `user:` directive in docker-compose. Use `USER_UID`/`USER_GID` env vars instead — s6-overlay needs root to start, then drops privileges.
|
||||
|
||||
### Never copy any config files
|
||||
All configs are symlinked. Copying a file breaks the link and causes drift from the repo.
|
||||
|
||||
## NAS Services Currently Using 1024:100
|
||||
- Gitea (`/mnt/nas/docker-data/gitea/data`)
|
||||
- Nextcloud app + db (`/mnt/nas/docker-data/nextcloud/`)
|
||||
|
||||
## Management Quick Reference
|
||||
|
||||
```bash
|
||||
# Docker service (from anywhere)
|
||||
cd /opt/docker/<service> && docker compose logs -f
|
||||
cd /opt/docker/<service> && docker compose restart
|
||||
cd /opt/docker/<service> && docker compose down && docker compose up -d
|
||||
|
||||
# Systemd services
|
||||
sudo systemctl status nginx copyparty netdata
|
||||
sudo systemctl restart nginx
|
||||
|
||||
# Nginx
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
|
||||
# NAS mount check
|
||||
mountpoint /mnt/nas && echo mounted
|
||||
```
|
||||
|
||||
## Keeping Skills Up To Date
|
||||
|
||||
After any change to service configuration, ports, paths, Docker UIDs, or operational rules:
|
||||
- Update this skill file (`homelab-context/SKILL.md`) to reflect the new state
|
||||
- Update `homelab-status/SKILL.md` if services are added or removed
|
||||
- This ensures future sessions always have accurate context without re-reading files
|
||||
|
||||
## Docs Reference
|
||||
- Full service install steps (for migration): `docs/services.md`
|
||||
- Network & security: `docs/network-security.md`
|
||||
- Troubleshooting: `docs/troubleshooting/`
|
||||
15
.claude/skills/homelab-status/SKILL.md
Normal file
15
.claude/skills/homelab-status/SKILL.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
name: homelab-status
|
||||
description: Check status of all homelab services at once.
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(docker *), Bash(systemctl *), Bash(mountpoint *), Bash(nginx *)
|
||||
---
|
||||
|
||||
Check and report status of all homelab services:
|
||||
|
||||
1. Run `docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"` to show all containers
|
||||
2. Run `systemctl is-active nginx copyparty netdata` to show systemd service states
|
||||
3. Run `mountpoint /mnt/nas` to confirm NAS is mounted
|
||||
4. Run `sudo nginx -t` to verify nginx config is valid
|
||||
5. Report any services that are stopped, failed, or unhealthy
|
||||
6. Note any containers not running that should be (gitea, jellyfin, portainer, qbittorrent, nextcloud)
|
||||
Reference in New Issue
Block a user