3.0 KiB
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 a deployment stack for the independent CAT-BODHI repository. Its Dockerfile fetches a pinned upstream commit and verifies the archive checksum; do not copy application source or model binaries into this repository. Generated assets and sprite output stay under ignored cat-bodhi/data/ paths.
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.docker compose -f cat-bodhi/compose.yml build: build the pinned upstream application and model image.curl https://cat-bodhi.xiteng.site/api/sprite-status: verify the deployed model API and required files.
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 external-source builds such as cat-bodhi, pin immutable commit hashes and include a verified archive checksum. Keep runtime mounts limited to persistent output, not source trees.
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, build the image, confirm the container starts cleanly, and require /api/sprite-status to report ready: true before publishing.
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.