================================================================
  WEBTOOL - cPANEL SHARED HOSTING DEPLOYMENT GUIDE
================================================================

REQUIREMENTS
------------
- cPanel hosting with Python support (Python 3.10+ recommended)
- Passenger WSGI enabled (most cPanel hosts include this)
- SSH access OR cPanel File Manager + Terminal
- At least 512MB RAM allocation


================================================================
STEP 1 — SET UP PYTHON APP IN CPANEL
================================================================

1. Log in to cPanel
2. Go to "Setup Python App" (under Software section)
3. Click "Create Application"
4. Fill in:
   - Python version : 3.10 (or 3.11/3.12 if available)
   - Application root: public_html/webtool
     (or any folder — e.g. just "webtool" if it's the main site)
   - Application URL : your domain or subdomain
     e.g. yourdomain.com  OR  tools.yourdomain.com
   - Application startup file: passenger_wsgi.py
   - Application Entry point : application
5. Click "CREATE"

cPanel will create:
  - A virtual environment at ~/virtualenv/webtool/
  - A passenger_wsgi.py stub (we will replace it)
  - An .htaccess file in the app root


================================================================
STEP 2 — UPLOAD PROJECT FILES
================================================================

METHOD A: File Manager (no SSH)
--------------------------------
1. Zip your entire webtool folder on your local PC:
   Right-click the "webtool" folder → Send to → Compressed (zip)

2. In cPanel → File Manager, navigate to:
   public_html/webtool/  (or wherever you set Application root)

3. Upload the zip file, then Extract it
4. Make sure these files are directly inside the app root:
   public_html/webtool/
     ├── passenger_wsgi.py
     ├── config.py
     ├── requirements.txt
     ├── app/
     └── instance/   ← create this empty folder manually

METHOD B: SSH / Terminal (recommended)
----------------------------------------
ssh user@yourdomain.com

cd ~/public_html
git clone https://github.com/yourrepo/webtool.git webtool
# OR upload via scp/rsync:
# scp -r ./webtool user@yourdomain.com:~/public_html/webtool


================================================================
STEP 3 — INSTALL DEPENDENCIES
================================================================

METHOD A: Via cPanel "Setup Python App" (easiest)
---------------------------------------------------
1. Go back to cPanel → Setup Python App
2. Click the pencil/edit icon on your app
3. Scroll down to "Install Python Packages"
4. In the package name box, paste each package one at a time
   and click Install, OR use the field at the bottom to point
   to requirements.txt

METHOD B: Via SSH Terminal
---------------------------
1. In cPanel "Setup Python App", click the app name
2. Copy the "Enter to the virtual environment" command shown,
   it looks like:
   source /home/USERNAME/virtualenv/webtool/3.10/bin/activate

3. Open cPanel Terminal (or SSH) and run:

   source /home/USERNAME/virtualenv/webtool/3.10/bin/activate
   cd ~/public_html/webtool
   pip install -r requirements.txt

   This installs all packages into the virtual environment.

NOTE: If lxml fails to install, try:
   pip install lxml --no-binary lxml

NOTE: If Pillow fails:
   pip install Pillow --no-binary :all:

NOTE: opencv-python-headless is optional (face blur tool).
      Skip it if it fails — face blur will show a graceful error.


================================================================
STEP 4 — CONFIGURE passenger_wsgi.py
================================================================

Make sure your passenger_wsgi.py contains exactly this:

---------- passenger_wsgi.py ----------
import sys
import os

sys.path.insert(0, os.path.dirname(__file__))

from app import create_app
application = create_app('production')
---------------------------------------

This file already exists in the project. No changes needed
unless cPanel created its own stub — in that case, replace
it with the content above.


================================================================
STEP 5 — SET UP THE SECRET KEY
================================================================

IMPORTANT: Change the secret key before going live.

METHOD A: Edit config.py directly
-----------------------------------
Open config.py and change this line:
   SECRET_KEY = os.environ.get('SECRET_KEY', 'webtool-secret-key-change-in-production')

Replace the default with a long random string:
   SECRET_KEY = os.environ.get('SECRET_KEY', 'AbC123XyZ789!@#$randomLongString...')

METHOD B: Set as environment variable in cPanel (more secure)
--------------------------------------------------------------
1. cPanel → Setup Python App → Edit your app
2. Scroll to "Environment Variables"
3. Add:  Name = SECRET_KEY   Value = (your random 32+ char string)
4. Save

Generate a random key in Python:
   python -c "import secrets; print(secrets.token_hex(32))"


================================================================
STEP 6 — CREATE REQUIRED FOLDERS & PERMISSIONS
================================================================

Run these commands via SSH or cPanel Terminal:

   cd ~/public_html/webtool

   # Create instance folder (holds SQLite database)
   mkdir -p instance

   # Create uploads folder (temp image files)
   mkdir -p app/static/uploads

   # Set write permissions
   chmod 755 instance
   chmod 755 app/static/uploads

IMPORTANT: The web server user needs write access to:
   - instance/         (SQLite database file)
   - app/static/uploads/  (temporary image uploads)


================================================================
STEP 7 — RESTART THE APPLICATION
================================================================

METHOD A: cPanel
-----------------
1. Go to cPanel → Setup Python App
2. Click the restart button (circular arrow icon) on your app
3. Wait 10-15 seconds

METHOD B: SSH
--------------
   touch ~/public_html/webtool/tmp/restart.txt
   # (create tmp folder first if needed: mkdir -p tmp)

METHOD C: .htaccess trick
---------------------------
Open .htaccess and save it (even without changes).
This triggers Passenger to reload.


================================================================
STEP 8 — FIRST RUN VERIFICATION
================================================================

1. Visit your domain in a browser: https://yourdomain.com
2. You should see the WebTools homepage with tool cards

3. Visit admin panel: https://yourdomain.com/admin/
   Default login:
     Username: admin
     Password: admin123

4. IMMEDIATELY change the admin password:
   Admin Panel → Settings → Change Password

5. Test a tool: click any tool card from the homepage


================================================================
STEP 9 — CONFIGURE .htaccess (if needed)
================================================================

cPanel Passenger apps need this in your app root .htaccess.
cPanel usually creates it automatically, but verify it contains:

---------- .htaccess ----------
PassengerEnabled On
PassengerAppRoot /home/USERNAME/public_html/webtool
PassengerBaseURI /
PassengerPython /home/USERNAME/virtualenv/webtool/3.10/bin/python
-------------------------------

Replace USERNAME with your actual cPanel username.
Replace 3.10 with your actual Python version.

If deploying to a SUBDIRECTORY (e.g. yourdomain.com/tools/):
   Change PassengerBaseURI to /tools


================================================================
STEP 10 — OPTIONAL: DOWNLOAD NLTK DATA
================================================================

For the Article Spinner tool to use WordNet synonyms,
download NLTK data once via SSH:

   source /home/USERNAME/virtualenv/webtool/3.10/bin/activate
   python -c "import nltk; nltk.download('wordnet'); nltk.download('stopwords'); nltk.download('averaged_perceptron_tagger')"

If NLTK data download fails (no internet from server),
the Article Spinner falls back to a built-in synonym dictionary
and will still work.


================================================================
TROUBLESHOOTING
================================================================

PROBLEM: 500 Internal Server Error
FIX:
  1. Check cPanel Error Logs: cPanel → Logs → Error Log
  2. Common causes:
     - Missing packages: run pip install -r requirements.txt
     - Wrong Python path in .htaccess
     - instance/ folder not writable

PROBLEM: 403 Forbidden
FIX:
  - Check .htaccess PassengerEnabled is set
  - Check file permissions: chmod 644 passenger_wsgi.py

PROBLEM: App shows old version after file changes
FIX:
  - Restart the app from cPanel → Setup Python App
  - OR: touch ~/public_html/webtool/tmp/restart.txt

PROBLEM: "Table already exists" error in logs
FIX:
  - Already fixed in this version (checkfirst=True)
  - If still occurring, delete instance/webtool.db and restart

PROBLEM: Image tools not working
FIX:
  - Ensure Pillow is installed: pip install Pillow
  - Check app/static/uploads/ is writable

PROBLEM: pytrends / Google Trends errors
FIX:
  - Google may block the request from server IPs
  - The tool shows a fallback message in this case
  - No fix needed — it's a Google-side rate limit

PROBLEM: "No module named 'cv2'" (face blur tool)
FIX:
  - Install: pip install opencv-python-headless
  - If it fails (common on shared hosting), the face blur tool
    will show "OpenCV not available on this server"
  - This does NOT affect any other tool


================================================================
FILE STRUCTURE ON SERVER (FINAL)
================================================================

~/public_html/webtool/          ← Application root
├── .htaccess                   ← Passenger config (auto-created)
├── passenger_wsgi.py           ← WSGI entry point
├── config.py                   ← App configuration
├── requirements.txt            ← Python dependencies
├── instance/
│   └── webtool.db              ← SQLite database (auto-created)
└── app/
    ├── __init__.py
    ├── models.py
    ├── helpers.py
    ├── extensions.py
    ├── admin/                  ← Admin panel
    ├── main/                   ← Homepage
    ├── tools/                  ← All 31 tools
    │   ├── seo/                ← 7 SEO tools
    │   ├── image/              ← 13 image tools
    │   └── webtools/           ← 11 web tools
    ├── templates/              ← HTML templates
    └── static/
        ├── css/
        ├── js/
        └── uploads/            ← Temp uploads (auto-cleaned)


================================================================
ADMIN PANEL QUICK REFERENCE
================================================================

URL:      https://yourdomain.com/admin/
Login:    admin / admin123  (CHANGE THIS!)

Features:
  - Dashboard: see all tools with active/inactive counts
  - Tools List: toggle any tool on or off instantly
  - Tool Edit: change tool name, description, icon, sort order
  - Password: change admin password

To HIDE a tool from users:
  Admin → Tools → click the toggle switch next to the tool
  The tool page still exists but returns 403 to users.

To ADD a new tool in future:
  1. Add entry to app/tools/__init__.py TOOL_REGISTRY
  2. Create app/tools/category/toolname.py
  3. Create app/templates/tools/category/toolname.html
  4. Restart app — it auto-appears in admin panel


================================================================
SECURITY CHECKLIST BEFORE GOING LIVE
================================================================

[ ] Change admin password from "admin123"
[ ] Set a strong SECRET_KEY (32+ random characters)
[ ] Ensure instance/ folder is NOT web-accessible
    Add to .htaccess if needed:
      RedirectMatch 404 /instance/
[ ] Ensure app/static/uploads/ only serves image files
[ ] Enable HTTPS on your domain (cPanel → SSL/TLS)
[ ] Consider adding rate limit values in config.py
    (RATE_LIMIT_DEFAULT = 30 requests/hour/IP/tool)


================================================================
SUPPORT
================================================================

Run locally for testing:
  cd d:/python/webtool
  python -c "from app import create_app; create_app('development').run(debug=True, port=5000)"

Then visit: http://127.0.0.1:5000/

================================================================