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