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
```