Skip to content

Commit 4c8fe62

Browse files
Mohitsharma44claude
Mohitsharma44
and
claude
committed
docs: add README for site contributors and infra maintainers
Root README targets research scientists managing content — covers editing workflow, deployment pipeline, file structure, and publications. Infra README documents architecture, Terraform files, CI/CD, IAM roles, domains, and bootstrap procedure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 1c279d5 commit 4c8fe62

2 files changed

Lines changed: 168 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 57 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,57 @@
1-
# website
2-
The CUSP Urban Observatory pubilc website
1+
# CUSP Urban Observatory
2+
3+
[![Deploy Site](https://github.com/CUSPUO/cuspuo.github.io/actions/workflows/deploy.yml/badge.svg)](https://github.com/CUSPUO/cuspuo.github.io/actions/workflows/deploy.yml)
4+
[![Terraform](https://github.com/CUSPUO/cuspuo.github.io/actions/workflows/terraform.yml/badge.svg)](https://github.com/CUSPUO/cuspuo.github.io/actions/workflows/terraform.yml)
5+
6+
The public website for the CUSP Urban Observatory.
7+
8+
**Live at:** [cuspuo.org](https://cuspuo.org) | [cuspuo.com](https://cuspuo.com)
9+
10+
## Editing the Site
11+
12+
The site is static HTML. To make changes:
13+
14+
1. Edit the relevant files (see [File Structure](#file-structure) below)
15+
2. Commit and push to the `master` branch (or open a PR and merge it)
16+
3. The site automatically deploys within ~1 minute
17+
18+
No build step, no manual deployment — just edit, push, and it's live.
19+
20+
## How Deployment Works
21+
22+
When changes are pushed to `master`:
23+
24+
1. **Sync** — All site files are uploaded to an S3 bucket
25+
2. **Cache clear** — CloudFront CDN cache is invalidated
26+
3. **Live** — Changes are available on all domains (cuspuo.org, cuspuo.com, and their www variants)
27+
28+
HTML files are cached for 5 minutes; other assets (images, CSS, JS) are cached for 24 hours.
29+
30+
## File Structure
31+
32+
```
33+
index.html Main site page
34+
UOpublications.html Publications listing
35+
404.html Custom error page
36+
comingsoon.html Placeholder page
37+
images/ Team photos and site images
38+
assets/ CSS, JavaScript, and fonts
39+
projects/ Project sub-pages (cdrhythms, visim_energy, etc.)
40+
bibtex2html/ Tool to convert BibTeX to HTML (see its own README)
41+
uo.bib BibTeX source for publications
42+
```
43+
44+
## Updating Publications
45+
46+
Publications are generated from `uo.bib` using the `bibtex2html/` tool:
47+
48+
```bash
49+
cd bibtex2html
50+
python bibtex2html_p3.py ../uo.bib template.html ../UOpublications.html
51+
```
52+
53+
See [`bibtex2html/README.md`](bibtex2html/README.md) for details.
54+
55+
## Infrastructure
56+
57+
The site is hosted on AWS (S3 + CloudFront) and managed with Terraform. See [`infra/README.md`](infra/README.md) for architecture, setup, and operational details.

‎infra/README.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Infrastructure
2+
3+
Terraform-managed AWS infrastructure for the CUSP Urban Observatory static site.
4+
5+
## Architecture
6+
7+
```
8+
┌─────────────┐
9+
│ Route53 │
10+
│ DNS Zones │
11+
└──────┬──────┘
12+
│ A/AAAA/CNAME
13+
▼
14+
┌──────────┐ ┌──────────────┐ ┌────────────┐
15+
│ ACM │──TLS──│ CloudFront │──OAC──│ S3 Bucket │
16+
│ Cert │ │ Distribution │ │ (private) │
17+
└──────────┘ └──────────────┘ └────────────┘
18+
│ │
19+
URL rewrite Security headers
20+
(index.html) (HSTS, CSP, etc.)
21+
```
22+
23+
- **S3** — Private bucket (`cuspuo-site`), accessible only via CloudFront OAC
24+
- **CloudFront** — CDN with TLS 1.2+, HTTP→HTTPS redirect, security headers, custom 404 page
25+
- **CloudFront Function** — Rewrites directory paths (`/path/` → `/path/index.html`)
26+
- **ACM** — TLS certificate with DNS validation for all active domains
27+
- **Route53** — DNS zones for `cuspuo.org` and `cuspuo.com` with A, AAAA, CNAME, and CAA records
28+
- **IAM** — GitHub Actions OIDC federation (no static credentials), separate deploy and terraform roles with permissions boundaries
29+
30+
## Active Domains
31+
32+
| Domain | DNS Provider | Status |
33+
|--------|-------------|--------|
34+
| cuspuo.org | Route53 | Active |
35+
| www.cuspuo.org | Route53 | Active |
36+
| cuspuo.com | Route53 | Active |
37+
| www.cuspuo.com | Route53 | Active |
38+
| muonetwork.com | GoDaddy | Deferred |
39+
| muonetwork.org | GoDaddy | Deferred |
40+
41+
To enable the GoDaddy domains, set `external_domains = ["muonetwork.com", "muonetwork.org"]` in `variables.tf` and follow the output instructions for manual DNS configuration.
42+
43+
## CI/CD Workflows
44+
45+
| Workflow | Trigger | Action |
46+
|----------|---------|--------|
47+
| **Deploy Site** | Push to `master` (non-infra files) | S3 sync + CloudFront invalidation |
48+
| **Terraform Plan** | PR with `infra/**` changes | Plan + Infracost cost estimate posted to PR |
49+
| **Terraform Apply** | Push to `master` with `infra/**` changes | Auto-apply (no manual approval) |
50+
51+
## Prerequisites
52+
53+
- **AWS CLI** with profile `muon` configured for account `217832331713`
54+
- **Terraform** >= 1.5.0
55+
56+
## Local Usage
57+
58+
All local terraform commands require the `muon` AWS profile:
59+
60+
```bash
61+
cd infra
62+
63+
# Set profile for the session
64+
export AWS_PROFILE=muon
65+
66+
# Standard workflow
67+
terraform init
68+
terraform plan
69+
terraform apply
70+
```
71+
72+
## State Management
73+
74+
- **State bucket:** `cuspuo-terraform-state` (S3, versioned, encrypted)
75+
- **Lock table:** `cuspuo-terraform-lock` (DynamoDB)
76+
- **State key:** `cuspuo-site/terraform.tfstate`
77+
78+
## Terraform Files
79+
80+
| File | Purpose |
81+
|------|---------|
82+
| `providers.tf` | AWS provider config and S3 backend |
83+
| `variables.tf` | Input variables (domains, bucket names, GitHub config) |
84+
| `locals.tf` | Computed values (domain lists, aliases) |
85+
| `state.tf` | State bucket and DynamoDB lock table |
86+
| `s3.tf` | Site bucket with OAC policy |
87+
| `acm.tf` | TLS certificate and DNS validation |
88+
| `cloudfront.tf` | CDN distribution, URL rewrite function, security headers |
89+
| `iam.tf` | OIDC provider, deploy/terraform roles, permissions boundaries |
90+
| `route53.tf` | DNS records (A, AAAA, CNAME, CAA) |
91+
| `outputs.tf` | Distribution ID, role ARNs, GoDaddy instructions |
92+
93+
## IAM Roles
94+
95+
| Role | Purpose | Trust |
96+
|------|---------|-------|
97+
| `cuspuo-github-deploy` | S3 sync + CloudFront invalidation | `master` branch only |
98+
| `cuspuo-github-terraform` | Infrastructure management | `master` branch, PRs, and `production-infra` environment |
99+
100+
Both roles use OIDC federation (no static AWS keys) and have permissions boundaries to prevent privilege escalation.
101+
102+
## Bootstrap from Scratch
103+
104+
If you ever need to recreate the infrastructure from zero:
105+
106+
1. Comment out the `backend "s3"` block in `providers.tf`
107+
2. Run `terraform init` (uses local state)
108+
3. Run `terraform apply -target=aws_s3_bucket.state -target=aws_s3_bucket_versioning.state -target=aws_s3_bucket_server_side_encryption_configuration.state -target=aws_s3_bucket_public_access_block.state -target=aws_dynamodb_table.state_lock`
109+
4. Uncomment the backend block
110+
5. Run `terraform init -migrate-state` to move state to S3
111+
6. Run `terraform apply` for the full infrastructure

0 commit comments

Comments
 (0)