From f9a2253742567940659dc5fea34be4394574d62f Mon Sep 17 00:00:00 2001
From: space <space@reversed.dev>
Date: Sat, 25 Jul 2026 00:32:12 +0200
Subject: [PATCH] docs: add comprehensive README with setup instructions and
 pnpm workspace config

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md           | 98 ++++++++++++++++++++++++++++++++++++++++++++-
 pnpm-workspace.yaml |  3 ++
 2 files changed, 100 insertions(+), 1 deletion(-)
 create mode 100644 pnpm-workspace.yaml

diff --git a/README.md b/README.md
index 504de35d..a23fc937 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,97 @@
-# Pr Previews (PP)
\ No newline at end of file
+# PR Previews (PP)
+
+> Self-hosted service that connects to a Gitea instance via webhook. When a PR is opened or updated, PP automatically provisions an AWS EC2 instance, builds and runs the project, and comments a live preview URL back on the PR.
+
+## Quick Start
+
+### Prerequisites
+
+- Docker & Docker Compose
+- Gitea instance with admin access
+- AWS account with EC2 permissions
+
+### Setup
+
+1. **Clone and configure:**
+   ```bash
+   cp example.env .env
+   # Edit .env — at minimum set SESSION_SECRET, PP_BASE_URL, and ENCRYPTION_KEY
+   # Generate ENCRYPTION_KEY: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+   ```
+
+2. **Start services:**
+   ```bash
+   docker compose up -d
+   ```
+
+3. **Open the web UI** at `http://localhost:5000` (or your configured PP_BASE_URL)
+
+4. **Create your admin account** on first login — you'll be prompted for a username and password.
+
+5. **Complete the setup wizard** to configure Gitea and AWS credentials.
+
+## Architecture
+
+```
+./backend/             # Node.js backend (rjweb-server + Prisma)
+./frontend/            # React + Vite + Tailwind CSS
+./prisma/schema.prisma # PostgreSQL schema
+./docker-compose.yml   # PP itself (backend + db)
+./Dockerfile           # Multi-stage build
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `DATABASE_URL` | PostgreSQL connection string |
+| `SESSION_SECRET` | Cookie signing secret (32+ random chars) |
+| `PP_BASE_URL` | Public URL of this PP instance (no trailing slash) |
+| `ENCRYPTION_KEY` | AES-256 key — 64 hex chars (32 bytes). Generate: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` |
+| `PORT` | Backend port (default: 5000) |
+| `LOG_LEVEL` | Logging level: trace/debug/info/warn/error (default: info) |
+
+## PP Commands (in PR comments)
+
+| Command | Action |
+|---|---|
+| `/pp rebuild` | Re-run build on existing EC2 instance |
+| `/pp stop` | Stop and terminate the preview |
+| `/pp start` | Start or restart a stopped/ignored preview |
+| `/pp logs` | Post last 50 lines of logs as a comment |
+| `/pp ignore` | Ignore all future events for this PR |
+
+## Required AWS IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [{
+    "Effect": "Allow",
+    "Action": [
+      "ec2:RunInstances", "ec2:TerminateInstances", "ec2:DescribeInstances",
+      "ec2:CreateSecurityGroup", "ec2:DeleteSecurityGroup",
+      "ec2:AuthorizeSecurityGroupIngress", "ec2:DescribeSecurityGroups",
+      "ec2:CreateKeyPair", "ec2:DeleteKeyPair", "ec2:CreateTags",
+      "sts:GetCallerIdentity"
+    ],
+    "Resource": "*"
+  }]
+}
+```
+
+## Development
+
+```bash
+# Database (via Docker)
+docker compose up -d pp-db
+
+# Run migrations
+cd backend && npx prisma migrate dev --schema=../prisma/schema.prisma
+
+# Backend (port 5000)
+cd backend && pnpm install && pnpm dev
+
+# Frontend dev server (port 3000, proxies API to backend)
+cd frontend && pnpm install && pnpm dev
+```
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 00000000..507e28e1
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,3 @@
+packages:
+  - backend
+  - frontend