navidocs/docs/DEPLOYMENT_STACKCP.md

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

# 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):

# 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):

# 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

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

cd ~/node_apps/navidocs/server
node db/init.js

6. Start Services

Meilisearch:

# 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:

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

# 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:

# 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):

REDIS_HOST=your-redis-instance.redis.cloud
REDIS_PORT=12345
REDIS_PASSWORD=your-password

Monitor with PM2

# 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!