Add README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..2102e80
--- /dev/null
+++ b/README
@@ -0,0 +1,99 @@
+# GitWeb + CloudFront + Terraform (EC2, SSH-only)
+
+This project provisions a minimal, secure-ish self-hosted Git server on AWS:
+
+- Git operations (clone/push/pull): **SSH only**
+- Web UI: **GitWeb behind CloudFront (HTTPS)**
+- EC2 HTTP (port 80): **not public**, allowed only from CloudFront origin-facing IP range
+- Admin access: **SSH restricted to your IP (/32)**
+
+## Architecture
+
+- EC2 (Ubuntu, t3.small) runs:
+  - git, git-shell
+  - gitweb + fcgiwrap
+  - nginx (serves GitWeb CGI)
+- CloudFront:
+  - exposes GitWeb to the internet over HTTPS
+  - origin is the EC2 public IP (Elastic IP)
+
+## Prerequisites
+
+- Terraform >= 1.14
+- AWS credentials configured (e.g. `aws configure`)
+- An existing EC2 Key Pair in the target region
+- Your public IP address (CIDR /32)
+
+## Deploy
+
+1) Go to terraform folder:
+```bash
+cd terraform
+````
+
+2. Create your tfvars:
+
+```bash
+cp terraform.tfvars.example terraform.tfvars
+# edit terraform.tfvars with your values
+```
+
+3. Init & apply:
+
+```bash
+terraform init
+terraform apply
+```
+
+Terraform will output:
+
+* the instance Public IP
+* an SSH command
+* the CloudFront URL for GitWeb
+
+## Test GitWeb UI
+
+Open the output URL:
+
+* `https://<cloudfront-domain>/cgi-bin/gitweb.cgi`
+
+## Create and push a repository (SSH)
+
+1. SSH into the instance as ubuntu (use the output ssh command).
+
+2. Create a bare repository:
+
+```bash
+sudo -u git git init --bare /var/lib/git/<project-name>.git
+```
+
+3. From your workstation, add remote and push:
+
+```bash
+git remote add origin ssh://git@<EC2_PUBLIC_IP>:/var/lib/git/<project-name>.git
+git push -u origin main
+```
+
+Notes:
+
+* This project copies the ubuntu user's `authorized_keys` to the `git` user at boot
+  so the same key pair can be used for both `ubuntu@` and `git@`.
+
+## Security model (what is enforced)
+
+* SSH (22): only from `my_ip_cidr`
+* HTTP (80): only from AWS-managed prefix list `com.amazonaws.global.cloudfront.origin-facing`
+* CloudFront viewer: HTTPS-only (CloudFront default cert)
+
+## Clean up
+
+```bash
+cd terraform
+terraform destroy
+```
+
+## Trade-offs (intentional, for simplicity)
+
+* No additional EBS volume: repositories live on the root disk
+* No end-to-end TLS to origin: origin is HTTP but restricted to CloudFront IPs only
+* No WAF, no logging to S3 (can be added as a next iteration)