homelab/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This repository manages a Docker Compose homelab. The root compose.yml defines the shared homelab_net network. Each service lives in its own directory with a local Compose file, for example traefik/compose.yml, authentik/compose.yml, gitea/compose.yml, seaweedfs/compose.yml, and chat/compose.yml. Runtime state and secrets belong in service-local data/, var/, letsencrypt/, .env, or similar untracked paths.

cat-bodhi/ is the main application code: index.html, game.js, styles.css, server.mjs, assets/, data/, and Python sprite tooling under tools/ and sprite_alpha_seg_pytorch/.

Build, Test, and Development Commands

• docker compose -f compose.yml up -d: create or update the shared network.
• docker compose -f traefik/compose.yml up -d: start a service stack; swap the path for other services.
• docker compose -f <service>/compose.yml config: validate a service Compose file before deploying it.
• docker compose -f <service>/compose.yml logs -f: inspect service logs during troubleshooting.
• cd cat-bodhi && npm run dev: run the local game and sprite import server on port 8080.
• cd cat-bodhi && npm run dev:ai:proxy: run the same server with Node environment proxy support.

Coding Style & Naming Conventions

Use two-space indentation in YAML, HTML, CSS, and JavaScript. Keep Compose service names, directories, and network aliases lowercase with hyphens, matching paths such as uptime-kuma and outpost-seaweedfs. Prefer explicit image tags over floating versions. Keep Traefik labels grouped with their service and preserve existing label patterns.

For cat-bodhi, keep the vanilla HTML/CSS/JS structure. Name JavaScript functions and variables in camelCase; use descriptive asset filenames such as decor-cat-bed.png.

Testing Guidelines

There is no centralized test suite. Validate infrastructure edits with docker compose -f <service>/compose.yml config and, when practical, restart only the affected service. For cat-bodhi, run npm run dev, open http://localhost:8080, and manually verify the changed workflow. If sprite processing changes, verify /api/sprite-status and /api/sprite-import.

Commit & Pull Request Guidelines

Recent history uses short Conventional Commit-style prefixes such as feat:, fix:, docs:, and refactor:, sometimes with Chinese descriptions. Keep commits focused on one service or feature. Pull requests should summarize changed services, include validation commands, call out environment or secret changes, and attach screenshots for UI changes.

Security & Configuration Tips

Do not commit real .env files, tunnel tokens, private keys, certificates, or generated service data. When adding a public route, confirm the intended Authentik mode: app-level OAuth/OIDC or Traefik ForwardAuth. Keep exposed domains and Traefik routers consistent with README.md.