adam/forgejo
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/forgejo.git synced 2026-09-30 03:03:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document CDK app and cdk.json in README (#46)
Some checks are pending
Deploy / deploy (push) Waiting to run
Details

Browse source 
The README covered runtime architecture and operations thoroughly but
never described the infrastructure-as-code layer itself. Readers had no
map of the CDK app: which files define the stacks, what cdk.json is, or
how to synth/diff. Add an Infrastructure as Code section covering the
project layout, the two stacks and their dependency, cdk.json, and the
common CDK commands.
This commit is contained in:
Adam Moussa 2026-07-10 16:07:40 -04:00 • committed by GitHub
parent 1fb12a965b
commit 72f0637fee
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 43 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
README.md
View file

@ -198,6 +198,49 @@ Run the setup script to create the GCS offsite bucket, service account, and stor
This creates the `sea-haven-backups` GCP project with a locked-retention GCS bucket. After running, configure the Storage Transfer job in the GCP Console using the AWS credentials from `forgejo/gcs-transfer-credentials`.
## Infrastructure as Code (CDK)
All AWS infrastructure is defined as an [AWS CDK](https://docs.aws.amazon.com/cdk/) v2 app written in TypeScript. There is no console-managed infrastructure — every resource in the sections above is synthesized from this repo.
### Project layout
| Path | Purpose |
|------|---------|
| `bin/app.ts` | CDK app entry point. Instantiates both stacks and wires the dependency between them. |
| `lib/forgejo-stack.ts` | Main stack (`forgejo`, us-east-1): EC2 instance, security groups, IAM, ALB target/DNS, secrets, EBS data volume, DLM snapshots, and the backup-verification construct. Holds the `FORGEJO_VERSION` constant. |
| `lib/forgejo-replica-stack.ts` | Replica stack (`forgejo-replica`, us-west-2): the S3 CRR replica bucket with versioning, Object Lock (Governance, 90d), and Glacier lifecycle. |
| `lib/constructs/backup-verification.ts` | `BackupVerification` construct — the daily verification Lambda, its schedule, and CloudWatch alarms. |
| `lambda/backup-verification/` | Python 3.12 handler (`app.py` + `requirements.txt`) bundled via `@aws-cdk/aws-lambda-python-alpha`. |
| `scripts/gcp-setup.sh` | One-time GCP offsite bucket/service-account provisioning (see [GCP Offsite Setup](#gcp-offsite-setup-one-time)). |
| `cdk.json` | CDK configuration — the `app` command and context feature flags. |
| `cdk.context.json` | Cached context lookups (VPC + AMI), committed so synth is deterministic. |
### Stacks
The app defines two stacks, both pinned to account `328440206208` with explicit kebab-case `stackName`s:
- **`forgejo-replica`** (us-west-2) — the S3 replica bucket. Deployed first; exports the replica bucket ARN and name.
- **`forgejo`** (us-east-1) — the main stack. Consumes the replica bucket ARN/name and declares a dependency on `forgejo-replica`, so CDK always deploys the replica first.
### `cdk.json`
`cdk.json` is the CDK entry configuration, committed to the repo:
- **`app`**: `npx ts-node bin/app.ts` — runs the TypeScript app directly (no separate `tsc` build step needed for synth).
- **`watch`**: include/exclude globs for `cdk watch`.
- **`context`**: CDK feature flags (e.g. `@aws-cdk/core:target-partitions`). Cached lookup context (VPC subnets, the AL2023 arm64 AMI) lives separately in `cdk.context.json` — `cdk.json` holds only feature flags.
`aws-cdk-lib` is pinned to an exact version (no `^`/`~`) per the CDK version policy; Dependabot keeps it current.
### Common commands
```bash
npm install
npm run synth # cdk synth — emit CloudFormation without deploying
npm run diff # cdk diff — diff local app against deployed stacks
npm run deploy # cdk deploy — deploy (pass -- --all for both stacks)
```
## Deployment
```bash