# Deployment Guide

## A. cPanel / CloudLinux (Passenger) Deployment

1. **Node application setup**
   - cPanel → *Setup Node.js App* → Create Application.
   - Node version: **18.x or later** (LTS).
   - Application root: `~/petzy/backend`
   - Application URL: e.g. `api.yourdomain.com`
   - Application startup file: `src/server.js`
2. **Environment variables** — in the Node.js App UI, add every key from
   `backend/.env.example` (DB_HOST, DB_NAME, DB_USER, DB_PASSWORD, JWT_SECRET,
   JWT_REFRESH_SECRET, FRONTEND_URL, SMTP_*, etc). Never commit real secrets.
3. **Install dependencies** — click *Run NPM Install* in the Node.js App UI,
   or via terminal:
   ```bash
   cd ~/petzy/backend
   source /home/<user>/nodevenv/petzy/backend/18/bin/activate
   npm install --production
   ```
4. **Database** — cPanel → *MySQL Databases*: create database `petzy_pos`
   plus a dedicated DB user with all privileges on it. Then, in
   **phpMyAdmin**, open the new database and use *Import* to load
   `database/schema.sql`, then `database/seed.sql` (or skip seed for a real
   deployment and use `npm run create-admin` instead).
5. **Uploads directory** — ensure `backend/uploads/**` subfolders exist and
   are writable (`chmod 755`). Do **not** expose `uploads/` via a public
   static alias — the app serves guest documents/media only through the
   authenticated `/api/media/file/:folder/:filename` route.
6. **Frontend build** — build locally or in a CI step (`npm run build` inside
   `frontend/`), then upload the contents of `frontend/dist/` to the static
   hosting root for your frontend subdomain/domain (e.g. `public_html/` or a
   separate *Static HTML* app pointing at `app.yourdomain.com`). Set
   `REACT_APP_API_URL` at build time to your API's public URL before running
   the build.
7. **Restart** — *Setup Node.js App* → **Restart**.

## B. Ubuntu VPS (Nginx + PM2) Deployment

```bash
# 1. System packages
sudo apt update && sudo apt install -y nodejs npm mysql-server nginx git

# 2. MySQL
sudo mysql_secure_installation
sudo mysql -e "CREATE DATABASE petzy_pos CHARACTER SET utf8mb4;"
sudo mysql -e "CREATE USER 'petzy'@'localhost' IDENTIFIED BY 'STRONG_PASSWORD';"
sudo mysql -e "GRANT ALL PRIVILEGES ON petzy_pos.* TO 'petzy'@'localhost'; FLUSH PRIVILEGES;"
mysql -u petzy -p petzy_pos < database/schema.sql
mysql -u petzy -p petzy_pos < database/seed.sql   # optional demo data

# 3. Backend
cd /var/www/petzy/backend
cp .env.example .env   # then edit with production values
npm install --production
npm install -g pm2
pm2 start src/server.js --name petzy-api
pm2 save
pm2 startup   # follow the printed instructions to enable boot-start

# 4. Frontend (build once, serve as static files via Nginx)
cd /var/www/petzy/frontend
cp .env.example .env   # set REACT_APP_API_URL to https://api.yourdomain.com/api
npm install
npm run build           # outputs frontend/dist

# 5. Nginx — API reverse proxy + static frontend
sudo tee /etc/nginx/sites-available/petzy <<'EOF'
server {
    listen 80;
    server_name app.yourdomain.com;
    root /var/www/petzy/frontend/dist;
    index index.html;
    location / { try_files $uri /index.html; }
}

server {
    listen 80;
    server_name api.yourdomain.com;
    location / {
        proxy_pass http://127.0.0.1:4001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;   # Socket.IO
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
EOF
sudo ln -s /etc/nginx/sites-available/petzy /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# 6. SSL
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d app.yourdomain.com -d api.yourdomain.com

# 7. Firewall
sudo ufw allow 'Nginx Full'
sudo ufw allow OpenSSH
sudo ufw enable
```

**Logs**: `backend/logs/combined.log` and `backend/logs/error.log` (Winston).
`pm2 logs petzy-api` for live process output.

**Restart after deploy**: `pm2 restart petzy-api`.

## C. Backup

```bash
# Database
mysqldump -u petzy -p petzy_pos > backup_$(date +%F).sql

# Restore
mysql -u petzy -p petzy_pos < backup_2026-08-14.sql

# Media/uploads
tar -czf uploads_$(date +%F).tar.gz backend/uploads/
```

No automatic destructive database operations are implemented (spec §122) —
backups are a manual/cron-scheduled `mysqldump`, never triggered by the app.