# Deployment & AWS Setup Guide

**Generated:** May 5, 2026  
**Purpose:** Overview of all deployable apps, deployment processes, and AWS infrastructure

---

## **APPS I CAN DEPLOY**

### 1. **PSQ Points Manager** (Port 3000)
- **Tech Stack:** Next.js 16.1.6 (Standalone mode), SQLite (Drizzle ORM)
- **Domain:** psq.paulfholland.com (HTTPS via Let's Encrypt)
- **Database:** SQLite file at `~/apps/psq/data/psq-points.db`
- **Backup:** S3 (nightly automated)

### 2. **Portfolio Analyzer (PA)** (Port 3001)
- **Tech Stack:** Next.js, stateless (no database)
- **Domain:** pa.paulfholland.com (HTTPS)
- **Use:** Auth redirects to login, crypto portfolio analysis

### 3. **Cost Dashboard** (Port 3002)
- **Tech Stack:** Next.js, stateless
- **Domain:** costs.paulfholland.com (HTTPS)
- **Data Source:** Reads OpenClaw session API (stateless, no database)
- **Use:** Tracks API costs by date/user

### 4. **Billable** (Port 3003)
- **Tech Stack:** Next.js, PostgreSQL (Prisma ORM)
- **Domain:** billable.paulfholland.com (HTTPS)
- **Database:** PostgreSQL (connection string in `.env`)
- **Backup:** S3 (nightly automated via pg_dump)
- **Use:** Invoice & time tracking for Paul & Rochelle

### 5. **ADAP** (Static HTML)
- **Tech Stack:** Plain HTML/CSS/JS
- **Domain:** digitalassetprofessionals.com (HTTPS)
- **Deployment:** Copied to `/var/www/adap`, no build process
- **No database, no backups needed**

---

## **DEPLOYMENT PROCESS FOR EACH APP**

### **PSQ Redeploy (Example - 6 minutes total)**

1. **Code Pull** (30 sec)
   ```bash
   cd ~/apps/psq && git pull
   ```
   - Fetch latest from GitHub repo

2. **Dependencies** (60 sec)
   ```bash
   npm install
   ```
   - Install/update npm packages

3. **Build** (120 sec)
   ```bash
   npm run build
   ```
   - Next.js compiles to `.next/standalone/` and `.next/static/`

4. **Copy Assets** (10 sec) — *Standalone-specific*
   ```bash
   cp -r public .next/standalone/
   cp -r .next/static .next/standalone/.next/
   ```
   - Copies logo, favicon, CSS/JS bundles
   - ⚠️ **Critical:** Standalone mode doesn't auto-include these

5. **Service Restart** (30 sec)
   ```bash
   systemctl --user restart psq.service
   ```
   - Stops old process, starts new one
   - Service file points to: `/home/ubuntu/apps/psq/.next/standalone/server.js`

6. **Health Check** (20 sec)
   ```bash
   curl https://psq.paulfholland.com/
   ```
   - Verify 200 response, no 502 errors

**Database Impact:** ZERO — SQLite file stays intact, migrations auto-run (if any)

---

### **PA Redeploy (Similar, 5 minutes)**

1. `git pull` (30 sec)
2. `npm install` (60 sec)
3. `npm run build` (90 sec)
4. `systemctl --user restart pa.service` (30 sec) — ⚠️ **No asset copy needed** (uses npm start, not standalone)
5. Health check (20 sec)

**Database Impact:** ZERO (stateless app)

---

### **Cost Dashboard Redeploy (4 minutes)**

Same as PA — stateless, no database, no special asset handling.

---

### **Billable Redeploy (5-6 minutes)**

1. `git pull` (30 sec)
2. `npm install` (60 sec)
3. `npm run build` (90 sec)
4. **Check Prisma migrations:** `npx prisma migrate status` (10 sec)
   - If pending → `npx prisma migrate deploy` (auto-runs on service start anyway)
5. `systemctl --user restart billable.service` (30 sec)
6. Health check (20 sec)

**Database Impact:** 
- Schema migrations run (auto) — can modify tables, add columns
- Data is SAFE (migrations are backwards-compatible)
- If you pull breaking changes, you need to handle them

---

### **ADAP Redeploy (1 minute)**

1. Copy HTML files to `/var/www/adap/`
2. NGINX already configured to serve from there
3. No build, no restart needed

**Database Impact:** NONE

---

## **AWS SETUP SUMMARY**

### **Infrastructure**
- **Compute:** EC2 instance (t4g.medium, arm64 architecture)
  - OS: Ubuntu 24.04 LTS
  - Region: ap-southeast-2 (Sydney)
  - IP: 3.25.129.223 (static Elastic IP)
  
- **Storage:** EBS volume (29GB gp3)
  - Root partition: 19GB → expanded to 29GB (April 7)
  - Current utilization: 70% (20GB used, 8.7GB free)
  - Growth rate: ~1-2% per week (manageable)

- **Backup:** S3 bucket
  - PSQ SQLite dumps nightly (104KB)
  - Billable PostgreSQL dumps nightly (18.8KB)
  - Retention: Ongoing (cost ~$0.01/month for storage)

### **How I Interface with AWS**

**1. EC2 SSH Access**
- SSH key stored locally on VM
- No Terraform/CloudFormation — manual infrastructure
- I only deploy to existing instance

**2. S3 Backups**
- AWS credentials at `~/.aws/credentials`
- Cron job calls `~/deployments/backup-databases.sh`
- Script uses `aws s3 cp` to upload database dumps nightly
- Minimal IAM policy (read/write to S3 only)

**3. No Direct AWS API Usage**
- No auto-scaling
- No RDS (PostgreSQL runs on same EC2)
- No security group management
- Let's Encrypt handles certificates locally

### **Apps Running on EC2**

| App | Port | Process | Memory | Status |
|-----|------|---------|--------|--------|
| PSQ | 3000 | node/.next/standalone/server.js | 65MB | ✅ Active |
| PA | 3001 | npm start (next) | 127MB | ⚠️ Crashing |
| Cost Dashboard | 3002 | npm start (next) | 40MB | ✅ Active |
| Billable | 3003 | npm exec next start | 172MB | ✅ Active |
| OpenClaw Gateway | 18789 | openclaw daemon | 850MB | ✅ Active |
| NGINX | 80/443 | NGINX reverse proxy | 10MB | ✅ Active |

---

## **CAPABILITIES NEEDED IF YOU SHIFT HOSTING**

### **Minimum Requirements**

1. **Linux VM** (Ubuntu 20.04+)
   - arm64 or amd64 (arm64 preferred for cost)
   - 2GB RAM minimum
   - 30GB SSD storage

2. **Node.js + npm**
   - v22+
   - Git CLI

3. **Reverse Proxy** (NGINX)
   - SSL termination
   - Port forwarding

4. **Database Servers**
   - PostgreSQL 15+ (for Billable)
   - SQLite 3+ (for PSQ)

5. **Process Management** (systemd)
   - Or Docker, PM2, supervisor

6. **Backup Storage**
   - S3, GCS, Azure Blob, or local
   - Nightly automated dumps

### **Optional**

- Email for cron alerts
- Monitoring/alerting
- CDN for static assets
- WAF/DDoS protection

---

## **IF YOU MIGRATE**

### **What Transfers Seamlessly**
- Source code (GitHub repos)
- Database backups (S3)
- Deployment scripts
- SSL certificates (Let's Encrypt)
- Systemd service files

### **What Needs Redoing**
- DNS pointing to new IP
- S3/backup credentials
- NGINX configuration
- SSH key pairs
- Cron job paths

---

## **ESTIMATED EFFORT**

- **Same provider (AWS → AWS):** 2-4 hours
- **Different provider (AWS → Digital Ocean):** 4-8 hours
- **Containerized (Docker):** 1-2 weeks

---

**Last Updated:** May 5, 2026