98 lines
2.8 KiB
Markdown
98 lines
2.8 KiB
Markdown
# 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
|
|
```
|