# 📘 Installation Guide — Dashboard Namnan v11

> Complete step-by-step installation for production deployment.

## 🎯 Prerequisites

- **OS**: Linux (Ubuntu 22.04+ recommended)
- **Python**: 3.10 or higher
- **MySQL**: 8.0+ (or MariaDB 10.5+)
- **nginx**: 1.18+
- **Domain**: with DNS pointing to your server
- **SSL**: Let's Encrypt (certbot)

```bash
# Verify versions
python3 --version    # Python 3.10+
mysql --version      # 8.0+
nginx -v             # 1.18+
certbot --version    # 1.0+
```

---

## 1. System Preparation

```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y python3 python3-pip python3-venv mysql-server nginx certbot python3-certbot-nginx
```

---

## 2. MySQL Setup

```bash
# Login as root
sudo mysql

# Create database + user
CREATE DATABASE namnan_dashboard CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'namnan_dash'@'localhost' IDENTIFIED BY 'YOUR_STRONG_PASSWORD';
GRANT ALL PRIVILEGES ON namnan_dashboard.* TO 'namnan_dash'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

### 2.1 Load Schema

```bash
cd /path/to/dashboard-namnan-v11
mysql -u namnan_dash -p namnan_dashboard < db/schema.sql
```

### 2.2 Load Data

**Option A: Full data dump** (recommended for production)
```bash
cd db
tar -xzf dumps.tar.gz
mysql -u namnan_dash -p namnan_dashboard < dumps/orders.sql
mysql -u namnan_dash -p namnan_dashboard < dumps/orders_history.sql
mysql -u namnan_dash -p namnan_dashboard < dumps/expenses.sql
mysql -u namnan_dash -p namnan_dashboard < dumps/expenses_history.sql
mysql -u namnan_dash -p namnan_dashboard < dumps/products.sql
mysql -u namnan_dash -p namnan_dashboard < dumps/product_aliases.sql
mysql -u namnan_dash -p namnan_dashboard < dumps/channels.sql
mysql -u namnan_dash -p namnan_dashboard < dumps/customers.sql
```

**Option B: Sample data only** (for development)
```bash
mysql -u namnan_dash -p namnan_dashboard < db/sample_data.sql
```

---

## 3. Backend Setup

```bash
# Create directory
sudo mkdir -p /opt/dashboard-api
sudo chown $USER:$USER /opt/dashboard-api

# Copy backend files
cp -r backend/* /opt/dashboard-api/

# Install Python packages
cd /opt/dashboard-api
pip3 install fastapi 'uvicorn[standard]' pymysql 'python-dotenv' pydantic requests

# Configure environment
cp deploy/env.example /opt/dashboard-api/.env
chmod 600 /opt/dashboard-api/.env
nano /opt/dashboard-api/.env
```

### 3.1 .env Configuration

```bash
# MySQL
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=namnan_dash
MYSQL_PASSWORD=YOUR_STRONG_PASSWORD
MYSQL_DB=namnan_dashboard

# API
DASHBOARD_API_KEY=$(openssl rand -hex 32)  # Generate random key
DASHBOARD_PORT=8300

# FB Ads
FB_ADS_API_URL=https://adsfb.namnan.co.th
```

### 3.2 Test Backend

```bash
cd /opt/dashboard-api
python3 -m uvicorn api.main:app --host 127.0.0.1 --port 8300

# In another terminal:
curl http://127.0.0.1:8300/health
# Should return: {"ok":true,"status":"healthy",...}
```

---

## 4. Systemd Service

```bash
# Copy service file
sudo cp deploy/dashboard-api.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable + start
sudo systemctl enable dashboard-api
sudo systemctl start dashboard-api

# Check status
sudo systemctl status dashboard-api
```

Expected output:
```
● dashboard-api.service - Dashboard Namnan API (FastAPI)
   Active: active (running) since ...
```

---

## 5. Frontend Setup (nginx)

### 5.1 Copy frontend files

```bash
# Create web root
sudo mkdir -p /var/www/dashboard.namnan.co.th
sudo chown -R www-data:www-data /var/www/dashboard.namnan.co.th

# Copy
cp -r frontend/* /var/www/dashboard.namnan.co.th/

# Set permissions
sudo chmod -R 755 /var/www/dashboard.namnan.co.th
```

### 5.2 nginx configuration

```bash
# Copy config
sudo cp deploy/dashboard.namnan.co.th.nginx.conf /etc/nginx/sites-enabled/dashboard.namnan.co.th

# Test config
sudo nginx -t

# Reload
sudo systemctl reload nginx
```

### 5.3 SSL with Let's Encrypt

```bash
# Get certificate
sudo certbot --nginx -d dashboard.namnan.co.th

# Auto-renew (already in certbot)
sudo certbot renew --dry-run
```

---

## 6. Cron Jobs

```bash
# Add cron entries
crontab -l > /tmp/cron.bak
cat deploy/crontab.txt >> /tmp/cron.bak
crontab /tmp/cron.bak

# Verify
crontab -l
```

Should include:
```
0 2 * * * /opt/dashboard-api/cron_rebuild.sh
30 23 * * * /usr/bin/python3 -c "import sys; sys.path.insert(0, '/opt/dashboard-api'); from api.fb_ads import sync; sync(days=2, dry_run=False)" >> /var/log/dashboard-api/fb_sync.log 2>&1
```

---

## 7. Verification

### 7.1 Backend health
```bash
curl https://dashboard.namnan.co.th/api/health
```

### 7.2 API auth
```bash
curl -H "X-API-Key: YOUR_API_KEY" https://dashboard.namnan.co.th/api/financial/summary?month=2026-07
```

### 7.3 Frontend
Open in browser:
- https://dashboard.namnan.co.th/ → main page
- https://dashboard.namnan.co.th/guide.html → user guide

### 7.4 FB Ads sync test
```bash
# Manual sync (dry run)
curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  "https://dashboard.namnan.co.th/api/sync/facebook-ads?days=2&dry_run=true"
```

---

## 8. Common Issues

### Issue 1: `pymysql.err.OperationalError: (1045, "Access denied")`
**Fix**: Check MySQL credentials in `/opt/dashboard-api/.env`

### Issue 2: `502 Bad Gateway` from nginx
**Fix**: Check backend is running
```bash
sudo systemctl status dashboard-api
sudo journalctl -u dashboard-api -n 50
```

### Issue 3: `ModuleNotFoundError: No module named 'pymysql'`
**Fix**: Install Python packages
```bash
pip3 install --break-system-packages pymysql fastapi uvicorn python-dotenv pydantic requests
```

### Issue 4: FB ads sync fails
**Fix**: Check `adsfb.namnan.co.th` is reachable
```bash
curl -I https://adsfb.namnan.co.th/public/trends?days=2
```

### Issue 5: API key 401 errors
**Fix**: Verify the key in `frontend/api.js` matches `.env`
```bash
# Get current key
grep DASHBOARD_API_KEY /opt/dashboard-api/.env

# Update frontend (or use ?api_key= URL param)
```

---

## 9. Backups

### 9.1 MySQL backup script

```bash
#!/bin/bash
# /usr/local/bin/namnan_dashboard_backup.sh
BACKUP_DIR=/var/backups/namnan_dashboard
mkdir -p $BACKUP_DIR
mysqldump -u namnan_dash -pYOUR_PASS namnan_dashboard | gzip > $BACKUP_DIR/$(date +%Y%m%d).sql.gz
find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete
```

Add to crontab:
```
0 1 * * * /usr/local/bin/namnan_dashboard_backup.sh
```

### 9.2 Restore from backup

```bash
gunzip < backup.sql.gz | mysql -u namnan_dash -p namnan_dashboard
```

---

## 10. Updating

```bash
# Backup first
mysqldump -u namnan_dash -p namnan_dashboard | gzip > /var/backups/pre-update-$(date +%s).sql.gz

# Pull new code
cd /path/to/dashboard-namnan-v11
# (or git pull)

# Update backend
cp backend/* /opt/dashboard-api/api/
sudo systemctl restart dashboard-api

# Update frontend
cp frontend/* /var/www/dashboard.namnan.co.th/
```

---

## 📞 Support

Issues? Check:
1. `sudo journalctl -u dashboard-api -n 100`
2. `/var/log/dashboard-api/rebuild.log`
3. `/var/log/dashboard-api/fb_sync.log`
4. nginx error log: `/var/log/nginx/error.log`

---

**Next**: See [API.md](API.md) for endpoint reference, [CHANGELOG.md](CHANGELOG.md) for version history.