docs: Add development and debug doc (#59)

* docs: Add development and debug doc
* docs: add .env example and container debug

Signed-off-by: Di Wang <[email protected]>

Author: hemslo

.env.example

@@ -0,0 +1,3 @@
+AWS_REGION=
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=

.tool-versions

@@ -1,3 +1,4 @@
 # this file is used by asdf to automatically select the correct tool versions
 # but it also serves as a reference for non-asdf users
 uv
+terraform 1.6.6

README.md

@@ -7,5 +7,117 @@ External Resources module to provision and manage RDS instances in AWS with App-
 * Terraform CDKTF
 * AWS provider
 * Random provider
-* Python 3.11
+* Python 3.12
 * Pydantic
+
+## Development
+
+Ensure `uv` is installed.
+
+Prepare local development environment:
+
+```shell
+make dev
+```
+
+This will auto create a `venv`, to activate in shell:
+
+```shell
+source .venv/bin/activate
+```
+
+Optional config `.env`:
+
+```shell
+cp .env.example .env
+```
+
+Edit `.env` file with credentials
+
+```shell
+qontract-cli --config $CONFIG get aws-creds $ACCOUNT
+```
+
+Export to current shell
+
+```shell
+source .env
+```
+
+## Debugging
+
+Export `input.json` via `qontract-cli` and place it in the current project root dir.
+
+```shell
+qontract-cli --config $CONFIG external-resources --provisioner $PROVISIONER --provider $PROVIDER --identifier $IDENTIFIER get-input > input.json
+```
+
+### On Host
+
+Ensure `cdktf` is installed
+
+```shell
+npm install --global [email protected]
+```
+
+Generate terraform config.
+
+```shell
+ER_INPUT_FILE="$PWD"/input.json cdktf synth
+```
+
+Ensure AWS credentials set in current shell, then use `terraform` to verify.
+
+```shell
+cd cdktf.out/stakcs/CDKTF
+terraform init
+terraform plan -out=plan
+terraform show -json plan > plan.json
+```
+
+Test validation logic
+
+```shell
+cd ../../..
+ER_INPUT_FILE="$PWD"/input.json python hooks/validate_plan.py cdktf.out/stacks/CDKTF/plan.json
+```
+
+### In Container
+
+Build image first
+
+```shell
+make build
+```
+
+Start container
+
+```shell
+docker run --rm -ti \
+  --entrypoint /bin/bash \
+  --mount type=bind,source=$PWD/input.json,target=/inputs/input.json \
+  --env-file .env \
+  er-aws-rds:prod
+```
+
+Generate terraform config.
+
+```shell
+cdktf synth
+```
+
+Use `terraform` to verify.
+
+```shell
+cd cdktf.out/stakcs/CDKTF
+terraform init
+terraform plan -out=plan
+terraform show -json plan > plan.json
+```
+
+Test validation logic
+
+```shell
+cd ../../..
+python hooks/validate_plan.py cdktf.out/stacks/CDKTF/plan.json
+```