35 lines
3.0 KiB
Markdown
35 lines
3.0 KiB
Markdown
# 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`.
|