38 lines
3.1 KiB
Markdown
38 lines
3.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- Core manifests: `main.tf` wires providers, `workspace.tf` defines the agent, and `services.tf`/`apps.tf` supply optional containers and apps.citeturn0search11
|
|
- `scripts.tf` maps Terraform to `scripts/*.sh`; add entries to `locals.workspace_agent_scripts` and keep those scripts idempotent because agents rerun them.
|
|
- `terraform.tfvars` carries defaults; store environment overrides in separate `*.auto.tfvars`.
|
|
- Workspace image comes from `../.devcontainer/Dockerfile`; after edits rebuild, retag, and bump `var.devcontainer_image` so Terraform targets a ready registry image.citeturn0search5
|
|
|
|
## Build, Test, and Development Commands
|
|
- `terraform init` — rerun after changing `required_providers`.
|
|
- `terraform fmt -recursive` — enforce two-space indentation before committing.
|
|
- `terraform validate` — catch schema or variable issues early.
|
|
- `terraform plan -var-file=terraform.tfvars -out plan.tfplan` — review planned changes; share the summary in reviews.
|
|
- `docker build -t <registry>/<image>:<tag> -f ../.devcontainer/Dockerfile ..` then `docker push` — refresh the devcontainer base before updating `devcontainer_image`.citeturn0search5
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Follow Terraform style: snake_case for locals/variables, singular resource names (`coder_agent.main`), and kebab-case for Docker/Coder `name`/`slug` fields.
|
|
- Group locals by concern and comment non-obvious transformations (e.g., startup script assembly).
|
|
- Keep `required_providers` aligned with Coder template defaults so `coder` and `docker` stay pinned.citeturn0search11
|
|
- Bash scripts must start with `#!/usr/bin/env bash` and `set -euo pipefail`; prefer functions for reusable logic.
|
|
|
|
## Testing Guidelines
|
|
- Run `terraform fmt -check` and `terraform validate` locally and in CI.
|
|
- Exercise feature toggles with targeted plans, e.g. `terraform plan -var enable_services=false`.
|
|
- When services are enabled, run `bash scripts/port-forward.sh` inside the workspace to confirm pgAdmin and Qdrant forwards.
|
|
- Skip committing `plan.tfplan`; attach `terraform show plan.tfplan` output in PRs.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- History is absent here; default to Conventional Commits (`feat:`, `fix:`, `chore:`) used across Coder templates.
|
|
- Scope commits narrowly and reference modules in the subject, e.g. `fix: tighten docker socket handling in workspace.tf`.
|
|
- PRs should note the user impact, include relevant `terraform plan` excerpts, call out service toggle defaults, and link tracking issues.
|
|
|
|
## Security & Configuration Tips
|
|
- Never commit secrets: provide `gitea_pat`, `github_pat`, or service passwords via overrides or template environment variables.
|
|
- When mount paths or ports move, update matching Terraform locals and scripts so port forwarding and health checks stay aligned.
|
|
- Rebuild the devcontainer image separately; this module assumes `var.devcontainer_image` already bundles required toolchains.
|
|
- Rely on registry scanning and caching; Coder guidance expects hardened, prebuilt images before workspaces launch.citeturn0search2
|