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