homelab/.claude/skills/homelab-context/SKILL.md

name, description, user-invocable

name	description	user-invocable
homelab-context	Background reference for the homelab repo. Auto-loads key facts about services, ports, paths, and operational rules when working in this project.	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

# 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/