pounce/DEPLOYMENT.md

Deployment Checklist — pounce

Quick Start (Local Development)

1. Backend

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

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

Open http://localhost:3000

---

Production Deployment

Option A: Docker Compose (Recommended)

# 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

# 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:

[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:

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

Frontend on Linux Server

# 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

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

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:

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

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

Manual

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

# 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

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

# Frontend
curl http://localhost:3000

---

Backup Database

SQLite

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

PostgreSQL

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

TLD Price Data

# 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:

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

# 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

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

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

Manual Trigger

# 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

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

# 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:

   curl http://localhost:8000/api/v1/admin/tld-prices/stats
   

2. If total_records: 0, run seed script:

   cd backend && python scripts/seed_tld_prices.py
   

3. Check Porkbun API is accessible:

   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:

# 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:

   docker-compose logs backend | grep -i email
   

3. Test SMTP connection:

   import smtplib
   server = smtplib.SMTP('smtp.host.com', 587)
   server.starttls()
   server.login('user', 'pass')
   

Scheduler Not Running

1. Check if backend started correctly:

   curl http://localhost:8000/health
   

2. View scheduler logs:

   docker-compose logs backend | grep -i "scheduler\|job"
   

3. Verify jobs are registered:

   • Should see "Scheduler configured" in startup logs