pounce/DEPLOYMENT.md

# Deployment Checklist — pounce

## Quick Start (Local Development)

### 1. Backend

```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp env.example .env
# Edit .env with your SECRET_KEY
uvicorn app.main:app --reload --port 8000
```

### 2. Frontend

```bash
cd frontend
npm install
cp env.example .env.local
npm run dev
```

Open http://localhost:3000

---

## Production Deployment

### Option A: Docker Compose (Recommended)

```bash
# Set environment variables
export SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")
export DB_PASSWORD=$(python3 -c "import secrets; print(secrets.token_hex(16))")
export CORS_ORIGINS=https://yourdomain.com
export API_URL=https://api.yourdomain.com

# Build and start
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop
docker-compose down
```

### Option B: Manual Deployment

#### Backend on Linux Server

```bash
# 1. Install Python 3.12
sudo apt update
sudo apt install python3.12 python3.12-venv

# 2. Clone and setup
cd /var/www
git clone <your-repo> pounce
cd pounce/backend

# 3. Create virtual environment
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 4. Configure
cp env.example .env
nano .env  # Set SECRET_KEY and DATABASE_URL

# 5. Create systemd service
sudo nano /etc/systemd/system/pounce-backend.service
```

Paste this content:

```ini
[Unit]
Description=pounce Backend
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/pounce/backend
Environment="PATH=/var/www/pounce/backend/venv/bin"
ExecStart=/var/www/pounce/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl enable pounce-backend
sudo systemctl start pounce-backend
sudo systemctl status pounce-backend
```

#### Frontend on Linux Server

```bash
# 1. Install Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs

# 2. Build
cd /var/www/pounce/frontend
npm ci
npm run build

# 3. Install PM2
sudo npm install -g pm2

# 4. Start with PM2
pm2 start npm --name "pounce-frontend" -- start
pm2 save
pm2 startup
```

#### Nginx Configuration

```bash
sudo nano /etc/nginx/sites-available/pounce
```

```nginx
server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location /api {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Enable and add SSL:

```bash
sudo ln -s /etc/nginx/sites-available/pounce /etc/nginx/sites-enabled/
sudo nginx -t
sudo certbot --nginx -d yourdomain.com
sudo systemctl reload nginx
```

---

## Security Checklist

- [ ] Generate strong SECRET_KEY: `python3 -c "import secrets; print(secrets.token_hex(32))"`
- [ ] Use HTTPS in production
- [ ] Set proper CORS_ORIGINS
- [ ] Use PostgreSQL instead of SQLite for production
- [ ] Configure firewall (allow 80, 443 only)
- [ ] Enable automatic security updates
- [ ] Set up database backups

---

## Updating the Application

### Docker

```bash
git pull
docker-compose down
docker-compose up -d --build
```

### Manual

```bash
git pull

# Backend
cd backend
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart pounce-backend

# Frontend
cd ../frontend
npm ci
npm run build
pm2 restart pounce-frontend
```

---

## Monitoring

### View Logs

```bash
# Docker
docker-compose logs -f backend
docker-compose logs -f frontend

# Systemd
sudo journalctl -u pounce-backend -f

# PM2
pm2 logs pounce-frontend
```

### Health Check

```bash
# Backend
curl http://localhost:8000/health

# Frontend
curl http://localhost:3000
```

---

## Backup Database

### SQLite

```bash
cp backend/domainwatch.db backup/domainwatch_$(date +%Y%m%d).db
```

### PostgreSQL

```bash
pg_dump -U pounce pounce > backup/pounce_$(date +%Y%m%d).sql
```

### TLD Price Data

```bash
# Export current prices to JSON (for versioning)
cd backend
python scripts/export_tld_prices.py

# The file is saved to: scripts/tld_prices_export.json
```

---

## Initial Data Seeding

### First-time Setup on New Server

After installing and starting the backend, seed the TLD price database:

```bash
cd backend
source venv/bin/activate

# Option A: Scrape fresh data from Porkbun API (recommended)
python scripts/seed_tld_prices.py

# Option B: Import from JSON backup
python scripts/import_tld_prices.py scripts/tld_prices_export.json
```

### Verify Data

```bash
# Check database stats
curl http://localhost:8000/api/v1/admin/tld-prices/stats

# Expected response:
# {
#   "total_records": 886,
#   "unique_tlds": 886,
#   "unique_registrars": 1
# }
```

---

## Scheduled Jobs (Cronjobs)

The backend automatically runs these scheduled jobs:

| Job | Schedule | Description |
|-----|----------|-------------|
| Domain Check | Configurable | Check all watched domains for availability |
| TLD Price Scrape | 03:00 UTC daily | Scrape latest prices from Porkbun API |
| Price Change Alerts | 04:00 UTC daily | Send email alerts for significant price changes (>5%) |

### Verify Scheduler is Running

```bash
# Check backend logs
docker-compose logs backend | grep -i scheduler

# Or for systemd:
sudo journalctl -u pounce-backend | grep -i scheduler
```

### Manual Trigger

```bash
# Trigger TLD scrape manually
curl -X POST http://localhost:8000/api/v1/admin/scrape-tld-prices

# Check price stats
curl http://localhost:8000/api/v1/admin/tld-prices/stats
```

---

## Email Notifications (Optional)

To enable email notifications for domain availability and price changes:

### 1. Configure SMTP in `.env`

```env
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_USER=your-email@domain.com
SMTP_PASSWORD=your-app-password
```

### 2. Supported Email Providers

| Provider | SMTP Host | Port | Notes |
|----------|-----------|------|-------|
| Gmail | smtp.gmail.com | 587 | Requires App Password |
| SendGrid | smtp.sendgrid.net | 587 | Use API key as password |
| Mailgun | smtp.mailgun.org | 587 | |
| Amazon SES | email-smtp.region.amazonaws.com | 587 | |

### 3. Test Email

```bash
# Test via API (create this endpoint if needed)
curl -X POST http://localhost:8000/api/v1/admin/test-email?to=you@email.com
```

### Email Types

1. **Domain Available Alert** — When a watched domain becomes available
2. **Price Change Alert** — When TLD price changes >5%
3. **Weekly Digest** — Summary of watched domains and price trends

---

## Troubleshooting

### TLD Prices Not Loading

1. Check if database has data:
   ```bash
   curl http://localhost:8000/api/v1/admin/tld-prices/stats
   ```

2. If `total_records: 0`, run seed script:
   ```bash
   cd backend && python scripts/seed_tld_prices.py
   ```

3. Check Porkbun API is accessible:
   ```bash
   curl -X POST https://api.porkbun.com/api/json/v3/pricing/get -d '{}'
   ```

### .ch Domains Not Working

Swiss (.ch) and Liechtenstein (.li) domains use a special RDAP endpoint:

```bash
# Test directly
curl https://rdap.nic.ch/domain/example.ch
```

The domain checker automatically uses this endpoint for .ch/.li domains.

### Email Not Sending

1. Check SMTP config in `.env`
2. Verify logs:
   ```bash
   docker-compose logs backend | grep -i email
   ```
3. Test SMTP connection:
   ```python
   import smtplib
   server = smtplib.SMTP('smtp.host.com', 587)
   server.starttls()
   server.login('user', 'pass')
   ```

### Scheduler Not Running

1. Check if backend started correctly:
   ```bash
   curl http://localhost:8000/health
   ```

2. View scheduler logs:
   ```bash
   docker-compose logs backend | grep -i "scheduler\|job"
   ```

3. Verify jobs are registered:
   - Should see "Scheduler configured" in startup logs