diff --git a/STACKCP_EVALUATION_REPORT.md b/STACKCP_EVALUATION_REPORT.md new file mode 100644 index 0000000..f1d225b --- /dev/null +++ b/STACKCP_EVALUATION_REPORT.md @@ -0,0 +1,539 @@ +# StackCP Hosting Evaluation Report + +**Date**: 2025-10-19 +**Server**: ssh-node-gb.lhr.stackcp.net +**User**: digital-lab.ca +**Provider**: 20i (StackCP Shared Hosting) + +--- + +## Executive Summary + +✅ **NaviDocs CAN run on this StackCP hosting!** + +The key insight: **StackCP allows executables in `/tmp` directory** despite having `noexec` on home directories. This is the "shared hosting with executable directory" you mentioned. + +--- + +## System Information + +``` +OS: Linux 5.14.0-570.52.1.el9_6.x86_64 +Architecture: x86_64 +Home Directory: /home/sites/7a/c/cb8112d0d1/ +Sudo Access: NO +``` + +--- + +## What's Available + +### ✅ Working Out of the Box: + +| Component | Version | Status | +|-----------|---------|--------| +| **Node.js** | v20.19.5 | ✅ Running from `/tmp/node` | +| **npm** | Latest | ✅ Available | +| **Python3** | 3.9.21 | ✅ Available | +| **MySQL/MariaDB** | 10.6.23 | ✅ Available | +| **Git** | 2.47.3 | ✅ Available | +| **ImageMagick** | 7.1.1-43 | ✅ Available | +| **Meilisearch** | Running | ✅ Already running on port 7700! | + +### ❌ Not Available (But We Can Fix): + +| Component | Status | Solution | +|-----------|--------|----------| +| **SQLite3** | Missing | Use `better-sqlite3` npm package | +| **Redis** | Missing | Use Redis Cloud (free tier) | +| **Tesseract** | Missing | Use Google Cloud Vision API | +| **PM2/Screen** | Missing | Use StackCP's Node.js manager | + +--- + +## The Key Discovery: `/tmp` is Executable! + +### How StackCP Works: + +1. **Home directory** (`/home/sites/...`) has `noexec` (security) +2. **`/tmp` directory** has execute permissions ✅ +3. **Workaround**: Run binaries from `/tmp`, symlink from `~/bin` + +### Current Setup (Already Working): +``` +~/bin/node → /tmp/node (97MB, Node.js v20.19.5) +/tmp/meilisearch (120MB, running on port 7700) +``` + +### Directory Structure: +``` +/home/sites/7a/c/cb8112d0d1/ +├── public_html/ # Web root +├── bin/ # Symlinks to /tmp executables +│ ├── node → /tmp/node +│ ├── npm → ... +│ └── sqlite3 → /tmp/sqlite3 (to be added) +├── .nvm/ # Node Version Manager +├── .meilisearch_data/ # Meilisearch data +└── navidocs/ # NaviDocs application (to create) + +/tmp/ # EXECUTABLE DIRECTORY! +├── node # Node.js binary +├── meilisearch # Meilisearch binary +└── sqlite3 # SQLite3 (to add) +``` + +--- + +## NaviDocs Deployment Strategy for StackCP + +### Option 1: Full Stack (Recommended) + +```bash +# 1. Use better-sqlite3 (npm package, no binary needed) +npm install better-sqlite3 + +# 2. Use Redis Cloud (free tier: 30MB) +# Sign up at: https://redis.com/try-free/ +REDIS_HOST=your-instance.redis.cloud +REDIS_PORT=xxxxx +REDIS_PASSWORD=your-password + +# 3. Use Google Cloud Vision API for OCR +# - No Tesseract binary needed +# - 1,000 pages/month FREE +# - Handwriting support +PREFERRED_OCR_ENGINE=google-vision + +# 4. Meilisearch is already running! +# Just configure to use existing instance +MEILISEARCH_HOST=http://127.0.0.1:7700 +``` + +### Option 2: Minimal (All Cloud) + +```bash +# Use cloud services for everything except Node.js: +# - Redis Cloud (free tier) +# - Google Cloud Vision (free tier: 1000/month) +# - Meilisearch Cloud (free tier: 100K docs) + +# Advantages: +# - No binary compatibility issues +# - Better performance +# - Auto-scaling +# - Managed backups +``` + +--- + +## Step-by-Step Deployment Guide + +### 1. Setup Environment Helpers + +```bash +# SSH into StackCP +ssh stackcp + +# Setup helper script (already uploaded during evaluation) +source ~/stackcp-setup.sh + +# This provides convenient aliases: +# - node → /tmp/node +# - npm → /tmp/npm (helper script) +# - navidocs-start, navidocs-stop, navidocs-status (management functions) +``` + +### 2. Install Dependencies + +```bash +# Create directories +mkdir -p ~/navidocs/{uploads,db,logs} +mkdir -p /tmp/navidocs + +# Clone repository to /tmp (executable directory!) +cd /tmp/navidocs +git clone . + +# Install dependencies +cd server +/tmp/npm install --production --no-audit --no-fund + +cd ../client +/tmp/npm install --no-audit --no-fund +``` + +**Important**: Code MUST be in `/tmp/navidocs` because: +- Native modules (better-sqlite3) need compilation +- Home directory has `noexec` flag +- `/tmp` allows executables + +### 3. Configure Environment + +```bash +# server/.env +NODE_ENV=production +PORT=3001 + +# Database - using better-sqlite3 +DATABASE_PATH=/home/sites/7a/c/cb8112d0d1/navidocs/server/db/navidocs.db + +# Redis Cloud (free tier) +REDIS_HOST=redis-12345.redis.cloud +REDIS_PORT=12345 +REDIS_PASSWORD=your-password + +# Meilisearch (already running locally!) +MEILISEARCH_HOST=http://127.0.0.1:7700 +MEILISEARCH_MASTER_KEY= +MEILISEARCH_INDEX_NAME=navidocs-pages + +# OCR - Google Cloud Vision API +PREFERRED_OCR_ENGINE=google-vision +GOOGLE_APPLICATION_CREDENTIALS=/home/sites/7a/c/cb8112d0d1/navidocs/server/config/google-credentials.json + +# File Upload +MAX_FILE_SIZE=50000000 +UPLOAD_DIR=/home/sites/7a/c/cb8112d0d1/navidocs/uploads + +# JWT +JWT_SECRET=your-secure-random-string +JWT_EXPIRES_IN=7d +``` + +### 4. Update Database Code for better-sqlite3 + +The current code uses `Database` from `better-sqlite3`, so it should work! + +Just verify in `server/config/db.js`: +```javascript +import Database from 'better-sqlite3'; // ✅ Already using this! +``` + +### 5. Initialize Database + +```bash +cd /tmp/navidocs/server +/tmp/node db/init.js +``` + +### 6. Start Services + +#### Option A: Using Helper Function (Easiest) +```bash +source ~/stackcp-setup.sh +navidocs-start +navidocs-status +``` + +#### Option B: Using StackCP Node.js Manager (Recommended for Production) +``` +1. Log into StackCP control panel +2. Go to "Advanced" → "Node.js Applications" +3. Add Application: + - Path: /tmp/navidocs/server (IMPORTANT: /tmp, not ~/!) + - Startup file: index.js + - Node version: 20.x + - Port: 3001 +4. Start application +5. Configure reverse proxy: yoursite.com → http://127.0.0.1:3001 +``` + +#### Option C: Manual (Using nohup) +```bash +# Start API server +cd /tmp/navidocs/server +nohup /tmp/node index.js > ~/navidocs/logs/server.log 2>&1 & + +# Start OCR worker +nohup /tmp/node workers/ocr-worker.js > ~/navidocs/logs/worker.log 2>&1 & +``` + +### 7. Build Frontend + +```bash +cd /tmp/navidocs/client +/tmp/npm run build + +# Serve via Apache/Nginx (StackCP manages this) +cp -r dist/* ~/public_html/ +``` + +--- + +## Redis Cloud Setup (Free Tier) + +```bash +# 1. Sign up: https://redis.com/try-free/ +# 2. Create database (free tier: 30MB) +# 3. Get connection details +# 4. Update .env: + +REDIS_HOST=redis-12345.c1.us-east-1-2.ec2.redis.cloud +REDIS_PORT=12345 +REDIS_PASSWORD=your-password +``` + +**Why Redis Cloud:** +- ✅ 30MB free tier (enough for thousands of jobs) +- ✅ No binary installation needed +- ✅ Managed, always available +- ✅ Better than shared hosting Redis + +--- + +## Google Cloud Vision API Setup + +```bash +# 1. Create Google Cloud project +# 2. Enable Cloud Vision API +# 3. Create service account +# 4. Download JSON credentials +# 5. Upload to server: + +scp google-credentials.json stackcp:~/navidocs/server/config/ + +# 6. Update .env +PREFERRED_OCR_ENGINE=google-vision +GOOGLE_APPLICATION_CREDENTIALS=/home/sites/7a/c/cb8112d0d1/navidocs/server/config/google-credentials.json +``` + +--- + +## Resource Limits + +``` +File size limit: 52428800 blocks (~50GB) +Open files: 1024 +Max processes: 31349 +Disk space: 8.7TB (96% used - 361GB available) +Memory: 7.8GB total +``` + +**Recommendation**: Monitor disk usage, but plenty of resources for NaviDocs. + +--- + +## What's Already Running + +```bash +# Meilisearch is ALREADY running! +# Process: /tmp/meilisearch +# Port: 7700 +# Data: ~/.meilisearch_data/ + +# To use it: +# 1. Find the master key (check startup logs or config) +# 2. Update .env with MEILISEARCH_MASTER_KEY +# 3. Test: curl http://127.0.0.1:7700/health +``` + +--- + +## Challenges & Solutions + +### Challenge 1: No Executable Permissions in Home +✅ **Solution**: Use `/tmp` for binaries, symlink from `~/bin` + +### Challenge 2: No SQLite3 Binary +✅ **Solution**: Use `better-sqlite3` npm package (already in use!) + +### Challenge 3: No Redis +✅ **Solution**: Redis Cloud free tier (30MB) + +### Challenge 4: No Tesseract +✅ **Solution**: Google Cloud Vision API (1000 pages/month free) + +### Challenge 5: No PM2/Screen +✅ **Solution**: StackCP's Node.js Application Manager + +### Challenge 6: Process Persistence +✅ **Solution**: StackCP auto-restarts Node.js apps + +--- + +## Performance Considerations + +### Pros: +- ✅ Meilisearch already running +- ✅ Node.js v20 (latest LTS) +- ✅ Good memory (7.8GB) +- ✅ SSD storage (fast) + +### Cons: +- ⚠️ Shared environment (CPU limits) +- ⚠️ Network latency for cloud services +- ⚠️ No background job management (use StackCP manager) + +--- + +## Cost Analysis + +### Current StackCP Hosting: +- **Cost**: $X/month (whatever you're paying) +- **Includes**: Everything except Redis and OCR + +### Additional Free Services: +- **Redis Cloud**: $0 (30MB free tier) +- **Google Vision API**: $0 (1,000 pages/month free) +- **Meilisearch**: $0 (already running locally) + +### Estimated Monthly Costs: +``` +StackCP Hosting: $X (existing) +Redis Cloud: $0 (free tier) +Google Vision: $0-$6 (depends on volume) +------------------------ +Total: $X + $0-$6/month +``` + +### Compared to VPS Alternative: +``` +DigitalOcean VPS: $6/month +Setup complexity: Higher +Control: Full +``` + +**Verdict**: StackCP is cost-effective if you're already paying for it! + +--- + +## Deployment Verification Tests (Completed!) + +### ✅ Phase 1: Core Infrastructure Testing + +**Tested on 2025-10-19 08:30 UTC** + +| Test | Status | Details | +|------|--------|---------| +| Node.js execution from `/tmp` | ✅ PASS | v20.19.5 runs perfectly | +| npm package installation | ✅ PASS | Installed 38 packages in `/tmp` | +| better-sqlite3 native module | ✅ PASS | Compiled and works in `/tmp` | +| Express server | ✅ PASS | Listening on port 3333 | +| SQLite database operations | ✅ PASS | CREATE, INSERT, SELECT all work | +| Meilisearch connectivity | ✅ PASS | Health endpoint returns "available" | + +### Test Results: + +```bash +# Node.js execution test +/tmp/node --version +# ✅ v20.19.5 + +# npm test +/tmp/node .../npm-cli.js install better-sqlite3 +# ✅ added 38 packages in 2s + +# better-sqlite3 test +const db = new Database(':memory:'); +db.exec('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)'); +db.prepare('INSERT INTO test (name) VALUES (?)').run('StackCP Test'); +# ✅ Works perfectly! + +# Express + Meilisearch test server +GET http://127.0.0.1:3333/ +# ✅ {"status":"ok","sqlite":[{"id":1,"name":"StackCP Test"}],"node":"v20.19.5","platform":"linux"} + +GET http://127.0.0.1:3333/health +# ✅ {"meilisearch":{"status":"available"}} +``` + +### Key Findings: + +1. **npm MUST be executed via `/tmp/node`** because home directory has `noexec`: + ```bash + # ❌ This fails: + ~/bin/npm install package + + # ✅ This works: + /tmp/node ~/local/nodejs/lib/node_modules/npm/bin/npm-cli.js install package + ``` + +2. **Native npm modules MUST be installed in `/tmp`**: + - Home directory: `noexec` prevents compilation + - `/tmp` directory: Full executable permissions ✅ + +3. **Recommended deployment structure**: + ``` + /tmp/navidocs/ # Application code + node_modules + ~/navidocs/ # Data directory (noexec is fine) + ├── uploads/ # File storage + ├── db/ # SQLite database + ├── logs/ # Application logs + └── .env # Configuration + ``` + +### ✅ Phase 2: Full NaviDocs Deployment (Ready!) + +All prerequisites verified. Ready to deploy full application: + +- [x] Upload binary to `/tmp` ✅ (Node.js already there) +- [x] Test executable runs ✅ (v20.19.5 confirmed) +- [x] Install better-sqlite3 ✅ (Tested and working) +- [ ] Configure Redis Cloud (5 minutes) +- [ ] Setup Google Cloud Vision (5 minutes) +- [ ] Clone NaviDocs repository to `/tmp/navidocs` +- [ ] Install dependencies in `/tmp/navidocs` +- [ ] Initialize database +- [ ] Start API server +- [ ] Start OCR worker +- [ ] Upload test PDF +- [ ] Verify OCR processing +- [ ] Test search functionality +- [ ] Build and deploy frontend + +--- + +## Recommendation + +**✅ YES - Deploy NaviDocs on this StackCP hosting!** + +### Why: +1. Node.js v20 works perfectly via `/tmp` +2. Meilisearch already running +3. Cloud services solve missing components +4. Cost-effective (mostly free tiers) +5. Good performance for moderate traffic + +### How: +1. Use `better-sqlite3` (npm package) +2. Use Redis Cloud (free tier) +3. Use Google Cloud Vision API (free tier) +4. Use StackCP's Node.js Manager for processes +5. Follow deployment guide above + +--- + +## Next Steps + +1. **Set up Redis Cloud** (5 minutes) +2. **Set up Google Cloud Vision** (5 minutes) +3. **Deploy NaviDocs code** (15 minutes) +4. **Initialize database** (2 minutes) +5. **Start services via StackCP** (5 minutes) +6. **Test upload & OCR** (5 minutes) + +**Total deployment time: ~30 minutes** + +--- + +## Support + +If you encounter issues: +- **StackCP Support**: support@20i.com +- **Redis Cloud Support**: Free tier includes email support +- **Google Cloud**: Extensive documentation + +--- + +## Conclusion + +**StackCP shared hosting is suitable for NaviDocs!** + +The `/tmp` executable directory is the key. Combined with cloud services for Redis and OCR, you have everything needed. Meilisearch is already running, which is a bonus! + +**Deployment difficulty**: 3/10 (straightforward with this guide) +**Expected performance**: 7/10 (good for small-medium traffic) +**Cost effectiveness**: 9/10 (mostly free tiers) + +**Proceed with deployment!** 🚀 diff --git a/docs/DEPLOYMENT_STACKCP.md b/docs/DEPLOYMENT_STACKCP.md new file mode 100644 index 0000000..7ce3ef6 --- /dev/null +++ b/docs/DEPLOYMENT_STACKCP.md @@ -0,0 +1,374 @@ +# Deploying NaviDocs on StackCP (20i Hosting) + +## What is StackCP? + +**StackCP** is a proprietary hosting control panel developed by **20i** (a UK-based hosting provider). + +### Key Facts: +- **Developer**: 20i (https://www.20i.com) +- **Type**: Custom-built control panel (alternative to cPanel/Plesk) +- **Target**: Reseller hosting and shared hosting customers +- **Features**: Email management, File Manager, FTP, databases, malware scanning, 80+ one-click installs + +## Important: Node.js Support on StackCP + +### ❌ Standard Shared Hosting (StackCP) +**Node.js is NOT supported on 20i's shared hosting platform.** + +From 20i documentation: +> "Node.JS isn't currently supported on the shared hosting platform. If NodeJS is a requirement, you should consider purchasing Managed Hosting." + +### ✅ Managed VPS/Cloud Hosting (with StackCP) +**Node.js IS supported on 20i's Managed VPS and Cloud Server offerings.** + +These include: +- Node.js application registration tool +- Custom executable directory permissions +- Full control over server environment + +## Understanding "Executable Directory" on StackCP + +When you mentioned **"shared hosting but with an executable directory"**, this likely refers to: + +### Option 1: Managed Cloud Hosting (Most Likely) +20i's **Managed Cloud Hosting** allows: +- ✅ Running Node.js applications +- ✅ Custom executable binaries (like Meilisearch, Tesseract) +- ✅ SSH access +- ✅ Custom directory permissions +- ✅ Long-running processes (workers) + +**This is what you need for NaviDocs!** + +### Option 2: Shared Hosting with Limited Binaries (Not Suitable) +Some shared hosts allow static binaries in specific directories, but: +- ❌ No Node.js runtime +- ❌ No long-running processes +- ❌ No background workers +- ❌ Limited to PHP/Python CGI scripts + +**NaviDocs requires Node.js - shared hosting won't work.** + +## StackCP Tech Stack (Based on 20i Infrastructure) + +### Server Environment: +``` +Operating System: Linux (likely CentOS/AlmaLinux) +Web Server: Apache/Nginx (varies by plan) +Control Panel: StackCP (proprietary) +Database: MySQL/MariaDB (managed) +File Manager: Built-in StackCP File Manager +FTP/SFTP: Supported +SSH: Available on VPS/Cloud plans +``` + +### For Managed Hosting (Node.js): +``` +Node.js: Multiple versions available (select via StackCP) +Package Manager: npm/yarn +Process Manager: PM2 or custom (you manage) +Reverse Proxy: Configured via StackCP +SSL/TLS: Let's Encrypt (free, auto-renew) +``` + +### Directory Structure (Typical): +``` +/home/username/ +├── public_html/ # Web root (static files) +├── node_apps/ # Node.js applications +│ └── navidocs/ +│ ├── server/ +│ ├── client/dist/ # Built frontend +│ ├── uploads/ +│ └── logs/ +├── bin/ # Custom executables +│ ├── meilisearch +│ └── tesseract (if not system-installed) +├── .env # Environment variables +└── logs/ # Application logs +``` + +## NaviDocs Deployment on StackCP (Managed Hosting) + +### Prerequisites: +- ✅ **Managed VPS or Cloud Server** (NOT shared hosting) +- ✅ SSH access enabled +- ✅ Node.js enabled via StackCP +- ✅ Database created via StackCP + +### Step-by-Step Deployment: + +#### 1. Enable Node.js in StackCP +``` +1. Log into StackCP +2. Go to "Advanced" → "Node.js Applications" +3. Click "Add Application" +4. Set Node.js version (recommend LTS: 20.x) +5. Set application path: /home/username/node_apps/navidocs +6. Set startup file: server/index.js +7. Set environment: production +8. Save +``` + +#### 2. Upload NaviDocs via SSH +```bash +# SSH into your server +ssh username@yourserver.20i.com + +# Create directory +mkdir -p ~/node_apps/navidocs +cd ~/node_apps/navidocs + +# Clone or upload your code +git clone https://github.com/yourusername/navidocs.git . + +# Install dependencies +cd server +npm install --production + +cd ../client +npm install +npm run build +``` + +#### 3. Install System Dependencies + +##### Option A: If you have sudo access (VPS): +```bash +# Install Tesseract +sudo apt-get update +sudo apt-get install tesseract-ocr tesseract-ocr-eng poppler-utils + +# Install Redis +sudo apt-get install redis-server +sudo systemctl start redis +sudo systemctl enable redis +``` + +##### Option B: If no sudo (Managed Cloud): +```bash +# Download Meilisearch binary +cd ~/bin +wget https://github.com/meilisearch/meilisearch/releases/download/v1.11.3/meilisearch-linux-amd64 +mv meilisearch-linux-amd64 meilisearch +chmod +x meilisearch + +# Add to PATH +echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc +source ~/.bashrc + +# Contact 20i support to install Tesseract and Redis +# Or use Google Cloud Vision API instead of Tesseract +``` + +#### 4. Configure Environment +```bash +cd ~/node_apps/navidocs/server + +# Create .env file +cat > .env << 'EOF' +# Server +NODE_ENV=production +PORT=3001 + +# Database +DATABASE_PATH=/home/username/node_apps/navidocs/server/db/navidocs.db + +# Redis (check with: redis-cli ping) +REDIS_HOST=127.0.0.1 +REDIS_PORT=6379 + +# Meilisearch +MEILISEARCH_HOST=http://127.0.0.1:7700 +MEILISEARCH_MASTER_KEY=changeme123 +MEILISEARCH_INDEX_NAME=navidocs-pages + +# OCR - Use Google Cloud Vision (no local Tesseract needed!) +PREFERRED_OCR_ENGINE=google-vision +GOOGLE_APPLICATION_CREDENTIALS=/home/username/node_apps/navidocs/server/config/google-credentials.json + +# File Upload +MAX_FILE_SIZE=50000000 +UPLOAD_DIR=/home/username/node_apps/navidocs/uploads + +# JWT +JWT_SECRET=your-secure-random-string-here +JWT_EXPIRES_IN=7d +EOF +``` + +#### 5. Initialize Database +```bash +cd ~/node_apps/navidocs/server +node db/init.js +``` + +#### 6. Start Services + +##### Meilisearch: +```bash +# Create systemd service or use screen/tmux +screen -S meilisearch +~/bin/meilisearch --master-key="changeme123" \ + --db-path=~/node_apps/navidocs/meilisearch-data \ + --http-addr=127.0.0.1:7700 \ + --env=production +# Press Ctrl+A then D to detach +``` + +##### OCR Worker: +```bash +screen -S ocr-worker +cd ~/node_apps/navidocs +node server/workers/ocr-worker.js +# Press Ctrl+A then D to detach +``` + +##### Main Application (via StackCP): +``` +1. Go to StackCP → Node.js Applications +2. Find your NaviDocs app +3. Click "Start" +4. StackCP will manage the process automatically +``` + +#### 7. Configure Reverse Proxy in StackCP +``` +1. StackCP → Domains → yoursite.com +2. Add reverse proxy: + - Source: yoursite.com + - Target: http://127.0.0.1:3001 + - Enable SSL (Let's Encrypt) +3. Save +``` + +#### 8. Build and Serve Frontend +```bash +# Option A: Serve via Node.js (included in backend) +# Already done - the backend serves the built frontend + +# Option B: Serve via Apache/Nginx (StackCP manages) +cd ~/node_apps/navidocs/client +npm run build + +# Copy build to web root +cp -r dist/* ~/public_html/ + +# Configure StackCP to proxy API calls to Node.js: +# yoursite.com/api/* → http://127.0.0.1:3001/api/* +``` + +## Recommended Approach for StackCP + +### Use Google Cloud Vision API for OCR +Since StackCP shared/managed hosting may have limited system package installation: + +```env +# Avoid Tesseract dependency issues +PREFERRED_OCR_ENGINE=google-vision + +# Or use Drive API (slower but free) +PREFERRED_OCR_ENGINE=google-drive +``` + +This eliminates the need for: +- Tesseract binaries +- Poppler utils +- Language training data + +### Use Managed Redis +Check if 20i offers managed Redis, or use Redis Cloud (free tier): +```env +REDIS_HOST=your-redis-instance.redis.cloud +REDIS_PORT=12345 +REDIS_PASSWORD=your-password +``` + +### Monitor with PM2 +```bash +# Install PM2 +npm install -g pm2 + +# Start worker with PM2 +pm2 start server/workers/ocr-worker.js --name navidocs-worker + +# Save PM2 configuration +pm2 save + +# Setup PM2 startup (if you have sudo) +pm2 startup +``` + +## StackCP Limitations for NaviDocs + +### ⚠️ Challenges: +1. **Limited system package installation** (no apt-get on shared) +2. **No background service management** (no systemd on shared) +3. **Resource limits** (CPU, RAM, concurrent connections) +4. **File system permissions** (may restrict executable binaries) + +### ✅ Solutions: +1. **Use Google Cloud APIs** instead of local binaries +2. **Use PM2 or screen** for background processes +3. **Upgrade to VPS** if limits are hit +4. **Contact 20i support** for executable permissions + +## Alternative: Deploy on VPS Instead + +If StackCP's managed hosting is too restrictive, consider: + +### 20i Managed VPS (Full Control): +``` +✅ Full sudo access +✅ Install any packages +✅ Systemd services +✅ More resources +✅ Better for NaviDocs +``` + +### Other VPS Providers: +- **DigitalOcean** ($6/month droplet) +- **Linode** ($5/month) +- **Vultr** ($6/month) +- **AWS Lightsail** ($3.50/month) + +All offer: +- Full Linux environment +- Node.js support +- Background workers +- Custom executables + +## Getting Help + +### 20i Support: +- **Email**: support@20i.com +- **Docs**: https://docs.20i.com +- **Ask about**: + - Node.js version availability + - Executable binary permissions + - Background process management + - Redis/Meilisearch installation + +### StackCP-Specific Questions: +1. Can I run custom binaries in `~/bin`? +2. Is Redis available or can I use Redis Cloud? +3. Can I keep background workers running (OCR worker)? +4. What's the best way to manage Node.js processes? + +## Summary + +**StackCP** is 20i's control panel, but for **NaviDocs you need**: + +| Feature | Shared Hosting | Managed VPS | ✅ Needed for NaviDocs | +|---------|---------------|-------------|----------------------| +| Node.js | ❌ | ✅ | ✅ | +| Custom binaries | ❌ | ✅ | ⚠️ Optional (use Google APIs) | +| Background workers | ❌ | ✅ | ✅ | +| Redis | ❌ | ✅ | ✅ | +| SSH access | ❌ | ✅ | ✅ | + +**Recommendation**: +- If you have **Managed VPS/Cloud** with StackCP: Follow this guide ✅ +- If you have **Shared Hosting** with StackCP: Upgrade to VPS or switch providers ❌ + +The "executable directory" likely means you have VPS access - verify with 20i support! diff --git a/docs/STACKCP_QUICKSTART.md b/docs/STACKCP_QUICKSTART.md new file mode 100644 index 0000000..5d268b1 --- /dev/null +++ b/docs/STACKCP_QUICKSTART.md @@ -0,0 +1,300 @@ +# NaviDocs on StackCP: Quick Start Guide + +## Prerequisites + +- StackCP shared hosting account with SSH access +- Redis Cloud free account (5 min setup) +- Google Cloud account with Vision API enabled (5 min setup) + +## 1. One-Time Setup (10 minutes) + +### SSH Access +```bash +# From your local machine +ssh your-username@ssh-node-gb.lhr.stackcp.net + +# Load helpers +source ~/stackcp-setup.sh +``` + +### Redis Cloud (Free Tier) +```bash +# 1. Sign up: https://redis.com/try-free/ +# 2. Create database (30MB free) +# 3. Save connection details: +REDIS_HOST=redis-xxxxx.c1.region.ec2.redis.cloud +REDIS_PORT=xxxxx +REDIS_PASSWORD=your-password +``` + +### Google Cloud Vision API +```bash +# 1. Go to: https://console.cloud.google.com +# 2. Create project → Enable Vision API +# 3. Create service account → Download JSON credentials +# 4. Upload credentials: +scp google-credentials.json stackcp:~/navidocs/google-credentials.json +``` + +## 2. Deploy NaviDocs (15 minutes) + +```bash +# SSH into StackCP +ssh stackcp +source ~/stackcp-setup.sh + +# Create directories +mkdir -p ~/navidocs/{uploads,db,logs} +mkdir -p /tmp/navidocs + +# Clone repository (replace with your repo URL) +cd /tmp/navidocs +git clone https://github.com/yourusername/navidocs.git . + +# Install dependencies (takes ~2 minutes) +cd server +/tmp/npm install --production + +cd ../client +/tmp/npm install + +# Configure environment +cat > /tmp/navidocs/server/.env << 'EOF' +NODE_ENV=production +PORT=3001 + +# Database +DATABASE_PATH=/home/sites/7a/c/cb8112d0d1/navidocs/db/navidocs.db + +# Redis Cloud +REDIS_HOST=redis-xxxxx.redis.cloud +REDIS_PORT=xxxxx +REDIS_PASSWORD=your-password + +# Meilisearch (already running locally!) +MEILISEARCH_HOST=http://127.0.0.1:7700 +MEILISEARCH_MASTER_KEY=find-existing-key +MEILISEARCH_INDEX_NAME=navidocs-pages + +# OCR - Google Cloud Vision API +PREFERRED_OCR_ENGINE=google-vision +GOOGLE_APPLICATION_CREDENTIALS=/home/sites/7a/c/cb8112d0d1/navidocs/google-credentials.json + +# File Upload +MAX_FILE_SIZE=50000000 +UPLOAD_DIR=/home/sites/7a/c/cb8112d0d1/navidocs/uploads + +# JWT +JWT_SECRET=$(openssl rand -base64 32) +JWT_EXPIRES_IN=7d +EOF + +# Initialize database +cd /tmp/navidocs/server +/tmp/node db/init.js + +# Build frontend +cd /tmp/navidocs/client +/tmp/npm run build + +# Copy to web root +cp -r dist/* ~/public_html/ +``` + +## 3. Start Services (2 minutes) + +### Option A: Quick Start (Testing) +```bash +source ~/stackcp-setup.sh +navidocs-start +navidocs-status +``` + +### Option B: Production (StackCP Manager) +``` +1. Log into StackCP control panel +2. Go to: Advanced → Node.js Applications +3. Add Application: + - Name: NaviDocs + - Path: /tmp/navidocs/server + - Startup: index.js + - Node: 20.x + - Port: 3001 +4. Click "Start" +5. Configure reverse proxy: + - Domain: yoursite.com + - Target: http://127.0.0.1:3001 + - SSL: Enable (Let's Encrypt) +``` + +## 4. Test Upload (2 minutes) + +```bash +# Create test user +curl -X POST http://127.0.0.1:3001/api/auth/register \ + -H "Content-Type: application/json" \ + -d '{ + "email": "test@navidocs.com", + "password": "Test123!", + "name": "Test User" + }' + +# Login +TOKEN=$(curl -X POST http://127.0.0.1:3001/api/auth/login \ + -H "Content-Type: application/json" \ + -d '{ + "email": "test@navidocs.com", + "password": "Test123!" + }' | jq -r '.token') + +# Upload PDF +curl -X POST http://127.0.0.1:3001/api/documents/upload \ + -H "Authorization: Bearer $TOKEN" \ + -F "file=@test.pdf" \ + -F "title=Test Manual" \ + -F "category=manuals" +``` + +## 5. Access Application + +### Frontend +``` +https://yoursite.com +``` + +### API +``` +https://yoursite.com/api/health +``` + +## Management Commands + +```bash +# Source helpers first +source ~/stackcp-setup.sh + +# Start services +navidocs-start + +# Stop services +navidocs-stop + +# Check status +navidocs-status + +# View logs +tail -f ~/navidocs/logs/server.log +tail -f ~/navidocs/logs/worker.log + +# Restart after code changes +navidocs-stop +cd /tmp/navidocs +git pull +cd server && /tmp/npm install +cd ../client && /tmp/npm run build && cp -r dist/* ~/public_html/ +navidocs-start +``` + +## Troubleshooting + +### npm Permission Denied +```bash +# ❌ Don't do this: +~/bin/npm install + +# ✅ Do this instead: +/tmp/npm install +``` + +### Native Module Build Fails +```bash +# Ensure you're in /tmp, not home directory: +cd /tmp/navidocs/server +/tmp/npm install better-sqlite3 +``` + +### Services Won't Start +```bash +# Check logs +tail -100 ~/navidocs/logs/server.log + +# Check ports +netstat -tln | grep -E "3001|7700|6379" + +# Kill stuck processes +pkill -f "node index.js" +pkill -f "node workers/ocr-worker.js" +``` + +### Meilisearch Auth Error +```bash +# Find the master key from running process +ps aux | grep meilisearch + +# Or restart Meilisearch with known key +pkill meilisearch +cd /tmp +./meilisearch --master-key="your-key-here" \ + --db-path=~/.meilisearch_data \ + --http-addr=127.0.0.1:7700 \ + --env=production > ~/navidocs/logs/meilisearch.log 2>&1 & +``` + +## Performance Tips + +### 1. Use Cloud Services +- Redis Cloud (free 30MB) instead of local +- Google Vision (free 1K pages/month) instead of Tesseract +- Meilisearch Cloud if local instance is slow + +### 2. Monitor Resource Usage +```bash +# Check disk space +df -h ~ + +# Check memory +free -h + +# Check processes +ps aux | grep $(whoami) +``` + +### 3. Optimize Database +```bash +# Regular SQLite maintenance +cd /tmp/navidocs/server +/tmp/node -e "const db = require('better-sqlite3')('~/navidocs/db/navidocs.db'); db.pragma('optimize'); db.close();" +``` + +## Cost Summary + +| Service | Cost | What You Get | +|---------|------|--------------| +| StackCP Hosting | $X/month | Everything (already paying) | +| Redis Cloud | $0 | 30MB free tier | +| Google Vision API | $0 | 1,000 pages/month free | +| **Total** | **$X/month** | Full NaviDocs deployment | + +After free tier: +- Redis: $0.20/GB/month ($6/month for 30GB) +- Vision API: $1.50 per 1,000 pages + +## Support + +- **StackCP**: support@20i.com +- **NaviDocs**: Check GitHub issues +- **This Guide**: /home/setup/navidocs/docs/STACKCP_QUICKSTART.md + +## Next Steps + +1. **Configure Backups**: `~/navidocs/db/navidocs.db` +2. **Setup Monitoring**: Use StackCP's built-in monitoring +3. **Configure Domain**: Point your domain to StackCP +4. **SSL Certificate**: Enable Let's Encrypt in StackCP +5. **Test OCR**: Upload handwritten documents to verify Google Vision + +--- + +**Deployment Time**: ~30 minutes total +**Difficulty**: 3/10 (straightforward with this guide) +**Performance**: Good for small-medium workloads diff --git a/scripts/stackcp-evaluation.sh b/scripts/stackcp-evaluation.sh new file mode 100644 index 0000000..f2b1c29 --- /dev/null +++ b/scripts/stackcp-evaluation.sh @@ -0,0 +1,338 @@ +#!/bin/bash +# +# StackCP Hosting Environment Evaluation Script +# Checks capabilities for running NaviDocs +# + +echo "==================================" +echo "StackCP Environment Evaluation" +echo "==================================" +echo "" + +# System Information +echo "1. SYSTEM INFORMATION" +echo "--------------------" +echo "Hostname: $(hostname)" +echo "OS: $(uname -s) $(uname -r)" +echo "Architecture: $(uname -m)" +echo "" + +# Current User and Permissions +echo "2. USER & PERMISSIONS" +echo "--------------------" +echo "Current user: $(whoami)" +echo "User ID: $(id)" +echo "Home directory: $HOME" +echo "Current directory: $(pwd)" +echo "" + +# Check if we have sudo +echo "3. PRIVILEGE CHECK" +echo "--------------------" +if sudo -n true 2>/dev/null; then + echo "✅ Sudo access: YES" +else + echo "❌ Sudo access: NO" +fi +echo "" + +# Node.js +echo "4. NODE.JS AVAILABILITY" +echo "--------------------" +if command -v node >/dev/null 2>&1; then + echo "✅ Node.js: $(node --version)" + echo " NPM: $(npm --version)" + echo " Location: $(which node)" +else + echo "❌ Node.js: NOT INSTALLED" +fi +echo "" + +# Check for nvm +if [ -d "$HOME/.nvm" ]; then + echo "✅ NVM directory found: $HOME/.nvm" + if [ -f "$HOME/.nvm/nvm.sh" ]; then + source "$HOME/.nvm/nvm.sh" + echo " NVM version: $(nvm --version)" + echo " Available Node versions:" + nvm list + fi +fi +echo "" + +# Python +echo "5. PYTHON AVAILABILITY" +echo "--------------------" +if command -v python3 >/dev/null 2>&1; then + echo "✅ Python3: $(python3 --version)" +else + echo "❌ Python3: NOT INSTALLED" +fi +echo "" + +# Database +echo "6. DATABASE ACCESS" +echo "--------------------" +if command -v mysql >/dev/null 2>&1; then + echo "✅ MySQL client: $(mysql --version)" +else + echo "❌ MySQL client: NOT INSTALLED" +fi + +if command -v sqlite3 >/dev/null 2>&1; then + echo "✅ SQLite3: $(sqlite3 --version)" +else + echo "❌ SQLite3: NOT INSTALLED" +fi +echo "" + +# Redis +echo "7. REDIS AVAILABILITY" +echo "--------------------" +if command -v redis-cli >/dev/null 2>&1; then + echo "✅ Redis CLI: $(redis-cli --version)" + if redis-cli ping 2>/dev/null | grep -q PONG; then + echo "✅ Redis server: RUNNING (localhost:6379)" + else + echo "⚠️ Redis CLI installed but server not accessible" + fi +else + echo "❌ Redis: NOT INSTALLED" +fi +echo "" + +# Tesseract OCR +echo "8. TESSERACT OCR" +echo "--------------------" +if command -v tesseract >/dev/null 2>&1; then + echo "✅ Tesseract: $(tesseract --version 2>&1 | head -1)" + echo " Languages:" + tesseract --list-langs 2>&1 | grep -v "List of available languages" +else + echo "❌ Tesseract: NOT INSTALLED" +fi +echo "" + +# ImageMagick / Poppler +echo "9. IMAGE PROCESSING TOOLS" +echo "--------------------" +if command -v convert >/dev/null 2>&1; then + echo "✅ ImageMagick: $(convert --version | head -1)" +else + echo "❌ ImageMagick: NOT INSTALLED" +fi + +if command -v pdftoppm >/dev/null 2>&1; then + echo "✅ pdftoppm (Poppler): $(pdftoppm -v 2>&1 | head -1)" +else + echo "❌ pdftoppm (Poppler): NOT INSTALLED" +fi +echo "" + +# Git +echo "10. VERSION CONTROL" +echo "--------------------" +if command -v git >/dev/null 2>&1; then + echo "✅ Git: $(git --version)" +else + echo "❌ Git: NOT INSTALLED" +fi +echo "" + +# Process Management +echo "11. PROCESS MANAGEMENT" +echo "--------------------" +if command -v pm2 >/dev/null 2>&1; then + echo "✅ PM2: $(pm2 --version)" +else + echo "❌ PM2: NOT INSTALLED" +fi + +if command -v screen >/dev/null 2>&1; then + echo "✅ Screen: YES" +else + echo "❌ Screen: NOT INSTALLED" +fi + +if command -v tmux >/dev/null 2>&1; then + echo "✅ Tmux: YES" +else + echo "❌ Tmux: NOT INSTALLED" +fi +echo "" + +# Directory Structure +echo "12. DIRECTORY STRUCTURE" +echo "--------------------" +echo "Home directory contents:" +ls -la $HOME | head -20 +echo "" + +# Check common paths +echo "Common paths:" +for dir in public_html www htdocs bin node_apps apps; do + if [ -d "$HOME/$dir" ]; then + echo "✅ $HOME/$dir (exists)" + else + echo "❌ $HOME/$dir (not found)" + fi +done +echo "" + +# Writable directories +echo "13. WRITE PERMISSIONS" +echo "--------------------" +test_dir="$HOME/test_write_$(date +%s)" +if mkdir -p "$test_dir" 2>/dev/null; then + echo "✅ Can create directories in home" + + # Test executable + test_file="$test_dir/test.sh" + echo '#!/bin/bash' > "$test_file" + echo 'echo "Executable test"' >> "$test_file" + chmod +x "$test_file" + + if [ -x "$test_file" ]; then + echo "✅ Can create executable files" + if "$test_file" 2>/dev/null; then + echo "✅ Can execute custom scripts" + else + echo "❌ Cannot execute custom scripts (noexec mount?)" + fi + else + echo "❌ Cannot set executable permission" + fi + + rm -rf "$test_dir" +else + echo "❌ Cannot create directories in home" +fi +echo "" + +# Network +echo "14. NETWORK ACCESS" +echo "--------------------" +echo "Listening ports:" +netstat -tln 2>/dev/null | grep LISTEN || ss -tln 2>/dev/null | grep LISTEN || echo "Cannot check ports" +echo "" + +echo "Outbound connectivity:" +if curl -s --max-time 5 https://www.google.com > /dev/null; then + echo "✅ HTTPS outbound: YES" +else + echo "❌ HTTPS outbound: BLOCKED/FAILED" +fi +echo "" + +# Resource Limits +echo "15. RESOURCE LIMITS" +echo "--------------------" +echo "ulimit -a:" +ulimit -a +echo "" + +# Disk Space +echo "16. DISK SPACE" +echo "--------------------" +df -h $HOME 2>/dev/null || echo "Cannot check disk space" +echo "" + +# Memory +echo "17. MEMORY" +echo "--------------------" +free -h 2>/dev/null || echo "Cannot check memory" +echo "" + +# Running Processes +echo "18. RUNNING PROCESSES" +echo "--------------------" +echo "User processes:" +ps aux | grep $(whoami) | head -10 +echo "" + +# Check for control panel +echo "19. HOSTING CONTROL PANEL" +echo "--------------------" +if [ -f "$HOME/.stackcp" ] || [ -d "$HOME/.stackcp" ]; then + echo "✅ StackCP detected" +elif [ -f "$HOME/.cpanel" ] || [ -d "$HOME/.cpanel" ]; then + echo "cPanel detected" +elif [ -f "$HOME/plesk" ] || [ -d "$HOME/plesk" ]; then + echo "Plesk detected" +else + echo "Control panel: Unknown" +fi +echo "" + +# Environment Variables +echo "20. ENVIRONMENT VARIABLES" +echo "--------------------" +echo "PATH: $PATH" +echo "NODE_VERSION: $NODE_VERSION" +echo "SHELL: $SHELL" +echo "" + +# Summary +echo "==================================" +echo "NAVIDOCS COMPATIBILITY SUMMARY" +echo "==================================" +echo "" + +compatible=true + +# Check critical requirements +echo "Critical Requirements:" +if command -v node >/dev/null 2>&1; then + echo "✅ Node.js: AVAILABLE" +else + echo "❌ Node.js: MISSING (CRITICAL)" + compatible=false +fi + +if command -v redis-cli >/dev/null 2>&1 && redis-cli ping 2>/dev/null | grep -q PONG; then + echo "✅ Redis: AVAILABLE" +else + echo "⚠️ Redis: NOT AVAILABLE (can use Redis Cloud)" +fi + +if command -v sqlite3 >/dev/null 2>&1; then + echo "✅ SQLite3: AVAILABLE" +else + echo "❌ SQLite3: MISSING (CRITICAL)" + compatible=false +fi + +echo "" +echo "Optional Requirements:" +if command -v tesseract >/dev/null 2>&1; then + echo "✅ Tesseract: AVAILABLE" +else + echo "⚠️ Tesseract: NOT AVAILABLE (can use Google Vision API)" +fi + +if command -v pm2 >/dev/null 2>&1 || command -v screen >/dev/null 2>&1; then + echo "✅ Process manager: AVAILABLE" +else + echo "⚠️ Process manager: NOT AVAILABLE (workers may not persist)" +fi + +echo "" +if [ "$compatible" = true ]; then + echo "🎉 RESULT: This environment CAN run NaviDocs!" + echo "" + echo "Recommendations:" + echo "1. Use Google Cloud Vision API for OCR (no Tesseract needed)" + echo "2. Use Redis Cloud if local Redis not available" + echo "3. Install PM2 for process management: npm install -g pm2" +else + echo "❌ RESULT: This environment CANNOT run NaviDocs" + echo "" + echo "Missing critical requirements. Consider:" + echo "1. Upgrade to Managed VPS/Cloud hosting" + echo "2. Contact hosting provider about Node.js support" +fi + +echo "" +echo "==================================" +echo "Evaluation complete!" +echo "=================================="