mirror of
https://github.com/Sea-Haven-Industries/file-share.git
synced 2026-09-30 15:53:18 +00:00
fdf1ad24dc
Some checks are pending
Deploy / deploy (push) Waiting to run
Co-authored-by: seahaven-openswe[bot] <296972425+seahaven-openswe[bot]@users.noreply.github.com> Co-authored-by: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
57 lines
No EOL
2.6 KiB
Markdown
57 lines
No EOL
2.6 KiB
Markdown
# AGENTS.md
|
|
|
|
Instructions for coding agents working in this repository.
|
|
|
|
## Infrastructure as Code principles
|
|
|
|
- **CDK + EC2**: this repo deploys an EC2 instance via CDK TypeScript. No Lambda, no SAM.
|
|
- **Lambda defaults (does not apply)** — this is a pure EC2 stack.
|
|
- **Exact-pin all CDK library versions** (`aws-cdk-lib`, `aws-cdk`, `constructs`). Never use `*` or `^` ranges.
|
|
- **Never commit** account IDs, role ARNs, VPC IDs, subnet IDs, or volume IDs in new code. The existing `cdk.context.json` already contains resolved values — do not add new deployment-specific identifiers without documented defaults.
|
|
- **Deploy with least-privilege IAM.** The instance role already has only `AmazonSSMManagedInstanceCore` + Secrets Manager read on `file-share/*`.
|
|
- **Verify**: `npm run build && npx cdk synth && npx cdk diff` before pushing. Do not commit `cdk.out/`.
|
|
|
|
## CDK directory layout
|
|
|
|
```
|
|
.
|
|
├── bin/
|
|
│ └── app.ts # CDK app entrypoint
|
|
├── lib/
|
|
│ └── file-share-stack.ts # All resource definitions
|
|
├── cdk.json # CDK context + config
|
|
├── cdk.context.json # Resolved context (committed)
|
|
├── package.json # Exact-pinned CDK dependencies
|
|
├── tsconfig.json
|
|
└── .github/
|
|
└── workflows/ # CI/CD
|
|
```
|
|
|
|
## `overrideLogicalId` — never remove
|
|
|
|
Removing `overrideLogicalId` on a deployed resource forces replacement. Never remove an existing call without documenting the replacement impact.
|
|
|
|
## Persistent EBS volumes
|
|
|
|
This repo's data volume (`vol-04d951cccacc435b5`) is **imported by ID**, not managed by CloudFormation. It survives instance replacement and stack deletion.
|
|
|
|
### Snapshot before an EC2-replacing deploy
|
|
|
|
Before any deploy that would replace the EC2 instance (AMI change, user-data change, instance type change):
|
|
|
|
1. Run `cdk diff` to confirm the instance will be replaced.
|
|
2. **Stop and ask for confirmation** — an instance replacement detaches the imported volume. A snapshot is the safety net.
|
|
3. If a DLM snapshot already exists from the same day, reference it rather than creating a duplicate.
|
|
|
|
## Security group rules
|
|
|
|
- Never open 0.0.0.0/0. All rules use specific CIDR ranges (`10.10.0.0/16` VPN, `10.20.0.0/16` VPC).
|
|
- SSM Session Manager for instance access — no SSH key, no public port 22.
|
|
|
|
## Secrets
|
|
|
|
Stored in AWS Secrets Manager (`file-share/smb-password`, `file-share/filebrowser-password`). The instance role reads them at boot. Do not embed secrets in UserData or source files.
|
|
|
|
## Documentation
|
|
|
|
The Confluence "AWS Architecture Map" (page 1540098) should be updated alongside any architecture change. |