# Trading Bite Watch-Time Portal
# Complete Deployment Guide

**Version:** 1.0  
**Production URL:** https://community.tradingbite.net/ytwatch  
**Audience:** Non-technical administrators

---

## Before You Begin

This guide walks you through deploying the Trading Bite Watch-Time Portal on your existing server, step by step. Each step includes the exact command to run and an explanation of what it does.

> **Important:** You already have another application running on this server (`tradingbite`, port 3001). This portal runs on a **separate port (3002)** and will not interfere with the existing application.

---

## Part 1 — Prerequisites

Before deploying, verify that the following are available on your server.

### 1.1 Check Node.js version

Connect to your server and run:

```bash
node --version
```

You need version **18 or higher**. If you see `v18.x.x`, `v20.x.x`, or higher, you are ready.  
If the version is lower, upgrade Node.js before continuing.

### 1.2 Check npm version

```bash
npm --version
```

You need version **9 or higher**.

### 1.3 Check PM2 is installed

```bash
pm2 --version
```

If PM2 is not installed, install it with:

```bash
npm install -g pm2
```

---

## Part 2 — Upload the Portal Files

### 2.1 Transfer the zip file to your server

Upload `trading-bite-ytwatch-portal.zip` to your server's home directory using SFTP, FileZilla, or your preferred file transfer tool.

### 2.2 Extract the files

Connect to your server via SSH and run:

```bash
cd /home/dulcfokx
unzip trading-bite-ytwatch-portal.zip -d ytwatch-portal
cd ytwatch-portal
```

---

## Part 3 — Configure Environment Variables

The portal uses a file called `.env.local` to store your secret settings. This file is never uploaded to the internet and stays on your server only.

### 3.1 Create the environment file

```bash
cp .env.example .env.local
```

### 3.2 Edit the environment file

```bash
nano .env.local
```

Fill in each value as described below. Use your keyboard to navigate, type your values, then press **Ctrl+O** to save and **Ctrl+X** to exit.

| Setting | What to put here |
|---|---|
| `ADMIN_USERNAME` | Your admin login username (e.g. `admin`) |
| `ADMIN_PASSWORD` | A strong password for the admin dashboard |
| `JWT_SECRET` | A long random string (at least 32 characters). Generate one at https://1password.com/password-generator/ and select "Secret" type. |
| `NEXT_PUBLIC_BASE_PATH` | `/ytwatch` — do not change this value |
| `NODE_ENV` | `production` — do not change this value |

Leave the Supabase fields empty unless you are using Supabase instead of the local file database.

### 3.3 Generate a secure JWT secret (alternative method)

If your server has OpenSSL installed, you can generate a secret automatically:

```bash
openssl rand -base64 32
```

Copy the output and paste it as the value of `JWT_SECRET` in `.env.local`.

---

## Part 4 — Install and Build

### 4.1 Run the install script

This script installs all required packages and builds the portal for production.

```bash
bash deploy/install.sh
```

This will take approximately **2–5 minutes**. When it finishes, you will see:

```
==> Build complete.
```

If you see an error, check that `.env.local` exists and all required values are filled in.

---

## Part 5 — Start the Portal

### 5.1 Start the portal with PM2

```bash
pm2 start deploy/ecosystem.config.js
```

You should see a table showing `ytwatch` with status **online**.

### 5.2 Save PM2 so the portal restarts after a server reboot

```bash
pm2 save
pm2 startup
```

Follow any instructions printed by `pm2 startup` to complete the auto-start setup.

### 5.3 Verify the portal is running

```bash
bash deploy/healthcheck.sh
```

You should see:

```
==> Health check: http://localhost:3002/ytwatch/api/auth/me
    Portal is running. HTTP status: 401
```

A status of `401` is correct — it means the portal is running and requires you to log in.

---

## Part 6 — Configure nginx

The portal runs on port 3002. Your nginx server needs to route requests for `/ytwatch` to that port.

### 6.1 Find your nginx configuration

The nginx config is typically located at one of these paths:

```
/etc/nginx/sites-available/community.tradingbite.net
/etc/nginx/conf.d/community.tradingbite.net.conf
/etc/nginx/nginx.conf
```

Open it with:

```bash
sudo nano /etc/nginx/sites-available/community.tradingbite.net
```

### 6.2 Add the proxy block

Inside your existing `server { }` block (the one for `community.tradingbite.net`), add the following section **before** the existing `location /` block:

```nginx
# Trading Bite Watch-Time Portal
location /ytwatch {
    proxy_pass http://localhost:3002;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    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;
    proxy_cache_bypass $http_upgrade;
}
```

### 6.3 Test and reload nginx

```bash
sudo nginx -t
sudo systemctl reload nginx
```

If `nginx -t` says `syntax is ok`, the configuration is correct.

---

## Part 7 — Verify the Live Deployment

### 7.1 Open the admin dashboard

Open your browser and go to:

```
https://community.tradingbite.net/ytwatch/admin
```

You should see the Trading Bite Watch-Time Portal login page.

### 7.2 Log in

Enter the `ADMIN_USERNAME` and `ADMIN_PASSWORD` you set in `.env.local`.

### 7.3 Confirm the dashboard loads

After logging in, you should see the admin dashboard with statistics panels.

---

## Ongoing Management

### View live logs

```bash
pm2 logs ytwatch --lines 50
```

### Restart the portal

```bash
pm2 restart ytwatch
```

### Stop the portal

```bash
pm2 stop ytwatch
```

### Check portal status

```bash
pm2 status ytwatch
```

### Update the portal (new release)

1. Back up the current release:
   ```bash
   cp -r /home/dulcfokx/ytwatch-portal /home/dulcfokx/ytwatch-portal.prev
   ```
2. Upload and extract the new zip file into `/home/dulcfokx/ytwatch-portal`
3. Copy the existing `.env.local` into the new folder:
   ```bash
   cp /home/dulcfokx/ytwatch-portal.prev/.env.local /home/dulcfokx/ytwatch-portal/.env.local
   ```
4. Run the install script:
   ```bash
   cd /home/dulcfokx/ytwatch-portal
   bash deploy/install.sh
   ```
5. Reload the portal:
   ```bash
   pm2 reload ytwatch
   ```
6. Verify it is running:
   ```bash
   bash deploy/healthcheck.sh
   ```

### Roll back to the previous release

If something goes wrong after an update:

```bash
cd /home/dulcfokx/ytwatch-portal
bash deploy/rollback.sh
```

---

## Troubleshooting

| Problem | Likely Cause | Solution |
|---|---|---|
| Login page shows "Internal Server Error" | Missing or incorrect `.env.local` values | Check `JWT_SECRET` and `ADMIN_PASSWORD` are set |
| Portal not reachable at `/ytwatch` | nginx not configured | Add the proxy block in Part 6 and reload nginx |
| Videos not loading | YouTube IFrame API blocked | Check browser console; ensure the domain is not blocking YouTube |
| Watch time not recording | Heartbeat API not reachable | Confirm `NEXT_PUBLIC_BASE_PATH=/ytwatch` in `.env.local` |
| Portal stopped after server reboot | PM2 startup not configured | Run `pm2 save` and `pm2 startup` again |

---

## Data and Backups

The portal stores viewing data in a local file at `.data/db.json`.

**Back up this file regularly:**

```bash
cp /home/dulcfokx/ytwatch-portal/.data/db.json \
   /home/dulcfokx/backups/ytwatch-db-$(date +%Y%m%d).json
```

To automate daily backups, add a cron job:

```bash
crontab -e
```

Add this line:

```
0 2 * * * cp /home/dulcfokx/ytwatch-portal/.data/db.json /home/dulcfokx/backups/ytwatch-db-$(date +\%Y\%m\%d).json
```

---

*Trading Bite Watch-Time Portal • Official YouTube IFrame Player*