navidocs/DEPLOYMENT_INDEX.md

NaviDocs StackCP Deployment - Complete Index

Status: Production Ready - Ready to Deploy Date: 2025-11-13 Application: NaviDocs v1.0.0 (Boat Documentation Management Platform)

---

Quick Start (5 Minutes)

1. Run Deployment Script

cd /home/setup/navidocs
chmod +x deploy-stackcp.sh
./deploy-stackcp.sh production

2. Build and Deploy Frontend

cd /home/setup/navidocs/client
npm install && npm run build
scp -r dist/* stackcp:~/public_html/digital-lab.ca/navidocs/

3. Start Application

• Option A: Login to StackCP Control Panel → Node.js Manager → Create Application

  • Start file: /tmp/navidocs/server/index.js
  • Port: 8001
  • Env vars: Load from ~/navidocs-data/.env

• Option B: SSH and restart service

  ssh stackcp "systemctl --user restart navidocs.service"
  

4. Verify It Works

ssh stackcp "curl -s http://localhost:8001/health | jq ."
# Expected: {"status":"ok","uptime":...}

Total Time: 30-45 minutes

---

Documentation Files

Essential Reading (Start Here)

File	Purpose	Read Time	When
DEPLOYMENT_SUMMARY.md	Executive overview of what's deploying	5 min	Before you start
STACKCP_DEPLOYMENT_GUIDE.md	Step-by-step deployment instructions	20 min	First-time deployment
STACKCP_QUICK_COMMANDS.sh	Copy-paste command reference	2 min	During deployment
DEPLOYMENT_ARCHITECTURE.md	System architecture and data flows	15 min	Understanding how it works

Reference Documentation

File	Purpose	When
STACKCP_ENVIRONMENT_REPORT.md	Pre-deployment checklist and verification	Before deployment
STACKCP_ARCHITECTURE_ANALYSIS.md	Deep technical analysis	If you want to understand tradeoffs
docs/DEVELOPER.md	Developer guide and API reference	When modifying code
IMPLEMENTATION_COMPLETE.md	Summary of 3 completed features	After deployment (optional)

---

File Locations

Local (Your Machine)

/home/setup/navidocs/
├── deploy-stackcp.sh                ← RUN THIS FIRST
├── STACKCP_DEPLOYMENT_GUIDE.md      ← Read this for detailed steps
├── STACKCP_QUICK_COMMANDS.sh        ← Copy commands from here
├── DEPLOYMENT_SUMMARY.md            ← Quick overview
├── DEPLOYMENT_ARCHITECTURE.md       ← How system works
├── DEPLOYMENT_INDEX.md              ← This file
├── server/                          ← Node.js backend code
│   ├── index.js                     (entry point)
│   ├── package.json
│   └── ... [services, routes, workers]
└── client/                          ← Vue 3 frontend code
    ├── package.json
    └── dist/                        (output after npm run build)

Remote (StackCP)

/tmp/navidocs/                       (EXECUTABLE - from /tmp, volatile)
├── server/                          (copied during deployment)
└── node_modules/                    (npm install --production)

~/navidocs-data/                     (PERSISTENT - home directory)
├── .env                             (environment config + secrets)
├── db/navidocs.db                   (SQLite database)
├── uploads/                         (user-uploaded documents)
└── logs/                            (application logs)

~/public_html/digital-lab.ca/navidocs/  (WEB-SERVED)
├── index.html                       (Vue 3 app)
├── assets/                          (JS/CSS bundles)
└── ... [static files]

---

What Each Documentation File Contains

DEPLOYMENT_SUMMARY.md ✓

Purpose: Quick executive overview Contains:

• What's being deployed (3 features)
• Architecture overview diagram
• Step-by-step quick start
• Key endpoints
• Troubleshooting table
• 15-minute read

Read if: You want a 5-minute overview before starting

STACKCP_DEPLOYMENT_GUIDE.md ✓

Purpose: Comprehensive step-by-step guide Contains:

• Pre-deployment checklist
• Automated script instructions
• Manual deployment steps (if script fails)
• Frontend build & deploy
• Service startup options
• Monitoring & maintenance
• Troubleshooting section
• Post-deployment configuration
• 45-minute read

Read if: You're doing the actual deployment

STACKCP_QUICK_COMMANDS.sh ✓

Purpose: Copy-paste command reference Contains:

• Full deployment commands
• Log viewing commands
• Service control commands
• Database operations
• File management
• Testing commands
• Troubleshooting commands
• 50+ ready-to-use commands

Read if: You want to quickly find a specific command

DEPLOYMENT_ARCHITECTURE.md ✓

Purpose: Deep technical architecture Contains:

• High-level system architecture diagram
• Data flow diagrams (3 scenarios: upload, search, timeline)
• Complete directory tree with explanations
• Technology stack details
• Performance characteristics
• Failure modes and recovery
• Security architecture
• Monitoring points
• 30-minute read

Read if: You want to understand how the system works

STACKCP_ENVIRONMENT_REPORT.md

Purpose: Pre-deployment verification Contains:

• StackCP environment assessment
• Node.js configuration
• Meilisearch status
• Disk space analysis
• Critical issues found & solutions
• Deployment checklist
• Next steps

Read if: You need to verify StackCP is ready (already done - all checks passed ✅)

STACKCP_ARCHITECTURE_ANALYSIS.md

Purpose: Technical tradeoffs and constraints Contains:

• Constraints of StackCP shared hosting
• Why /tmp is volatile vs ~/ is persistent
• Decision matrix (StackCP vs VPS)
• Security risks specific to shared hosting
• Cost analysis

Read if: You want to understand why deployment is structured this way

docs/DEVELOPER.md

Purpose: Developer reference Contains:

• Project structure
• Architecture overview
• API endpoints
• Environment variables
• Development setup
• Testing procedures
• Performance benchmarks

Read if: You need to modify code or understand API structure

---

Deployment Steps Overview

Step 1: Preparation (5 min)

1. Review pre-deployment checklist ✅ (All checks passed)
2. Verify SSH connection works
3. Ensure you're in /home/setup/navidocs directory

Step 2: Run Automated Deployment (15 min)

./deploy-stackcp.sh production

This script handles:

• Uploading code to /tmp/navidocs
• Installing npm dependencies
• Creating .env file
• Initializing SQLite database
• Running smoke tests

Step 3: Build Frontend (5 min)

cd client && npm install && npm run build
scp -r dist/* stackcp:~/public_html/digital-lab.ca/navidocs/

Step 4: Start Application (5 min)

• Configure in StackCP Control Panel, or
• Run: ssh stackcp "systemctl --user restart navidocs.service"

Step 5: Verify (5 min)

ssh stackcp "curl -s http://localhost:8001/health"
# Visit: https://digital-lab.ca/navidocs/

---

Command Cheat Sheet

Deployment

# Full automated deployment
./deploy-stackcp.sh production

# Build frontend
cd client && npm run build

# Deploy frontend
scp -r client/dist/* stackcp:~/public_html/digital-lab.ca/navidocs/

# Start service
ssh stackcp "systemctl --user restart navidocs.service"

Monitoring

# Check if running
ssh stackcp "curl -s http://localhost:8001/health | jq ."

# View logs
ssh stackcp "tail -f ~/navidocs-data/logs/app.log"

# Check disk usage
ssh stackcp "du -sh ~/navidocs-data/"

Troubleshooting

# Restart service
ssh stackcp "systemctl --user restart navidocs.service"

# Fix node permissions
ssh stackcp "chmod +x /tmp/node"

# Reinstall dependencies
ssh stackcp "source ~/.nvm/nvm.sh && cd /tmp/navidocs && npm install --production"

# Kill stuck process
ssh stackcp "pkill -9 node"

---

Common Issues & Solutions

Issue	Solution
"Node not found"	ssh stackcp "chmod +x /tmp/node"
"npm not found"	Use NVM: source ~/.nvm/nvm.sh && npm
"Port 8001 in use"	Kill: ssh stackcp "pkill node"
"Database locked"	Kill: ssh stackcp "pkill -9 node"
"Disk full"	Archive: find ~/navidocs-data/uploads -mtime +30 -delete
"Frontend not loading"	Check: ssh stackcp "ls -la ~/public_html/digital-lab.ca/navidocs/"
"Search not working"	Restart: ssh stackcp "curl -s http://localhost:7700/health"

---

Success Criteria

After deployment, verify:

• ✅ API Running: curl http://localhost:8001/health → 200 OK
• ✅ Database: File exists ~/navidocs-data/db/navidocs.db with size > 0
• ✅ Frontend: Browser loads https://digital-lab.ca/navidocs/
• ✅ Login: Can create account and login
• ✅ Upload: Can upload PDF document
• ✅ OCR: Document processes in <10s
• ✅ Search: Returns results instantly
• ✅ Timeline: Shows activity events
• ✅ Logs: No ERROR entries: grep ERROR ~/navidocs-data/logs/app.log | wc -l → 0

---

Features Being Deployed

Feature 1: Smart OCR (36x Performance)

• Extracts native text from PDFs first (2-3s)
• Only OCRs pages with <50 characters of text
• Result: 100-page PDF in 5s (was 180s)
• Status: ✅ Production Ready

Feature 2: Multi-Format Upload

• PDF: Native + OCR fallback
• Images: JPG/PNG with OCR
• Word: DOCX with Mammoth
• Excel: XLSX with Sheet parsing
• Text: TXT/MD direct read
• Status: ✅ Production Ready

Feature 3: Timeline Activity

• Logs all document uploads/deletions
• Shows activity history with timestamps
• User attribution (who did what)
• Status: ✅ Production Ready

---

Architecture Decision: Why This Configuration?

Why Code in /tmp and Data in ~/navidocs-data/?

• /tmp/navidocs: Executable directory, where Node.js can run
• ~/navidocs-data: Persistent directory, survives /tmp cleanup cycles
• Separation: Isolates volatile code from critical data

Why Nginx Reverse Proxy?

• Static files (Vue frontend) served fast
• API requests proxied to Node.js on port 8001
• Single HTTPS certificate
• Rate limiting and caching at reverse proxy level

Why SQLite Not MySQL?

• StackCP includes both, but SQLite needs no separate service
• Simple backups (single file)
• Sufficient for this use case (database < 1 GB)
• Perfect for shared hosting

Why Meilisearch?

• Full-text search engine, purpose-built
• Blazingly fast (<10ms searches)
• Tenant-aware (multi-org support)
• Docker container available if needed

---

Timeline: Expected Duration

Step	Duration	Notes
Run deployment script	10-15 min	Mostly npm install
Build frontend	3-5 min	Vite build + optimization
Upload frontend	1-2 min	SCP to StackCP
Start service	<1 min	systemctl restart
Verify deployment	2-3 min	Health checks
Total	25-35 min	Ready to use

---

Post-Deployment To-Do List

After successful deployment:

1. Test with sample boat documents
2. Train users on upload/search workflows
3. Set up automated daily backups
4. Configure monitoring alerts
5. Create user documentation
6. Test disaster recovery (database restore)
7. Review logs for first week
8. Optimize based on actual usage patterns

---

Support & Escalation

If Deployment Fails

1. First: Check SSH connection

   ssh stackcp "echo 'Connection OK'"
   

2. Second: Check Node.js is executable

   ssh stackcp "chmod +x /tmp/node && /tmp/node --version"
   

3. Third: Review deployment script output

   ./deploy-stackcp.sh production 2>&1 | tee deployment.log
   

4. Fourth: Check logs on StackCP

   ssh stackcp "tail -50 ~/navidocs-data/logs/app.log"
   

5. Last: Rollback to previous version

   ssh stackcp "cd /tmp && git clone ... && npm install --production"
   

---

Document Map for Quick Reference

START HERE
    │
    ├─→ DEPLOYMENT_SUMMARY.md
    │   (5-min overview)
    │
    └─→ Need step-by-step?
        │
        ├─→ STACKCP_DEPLOYMENT_GUIDE.md
        │   (Detailed 45-minute guide)
        │
        ├─→ STACKCP_QUICK_COMMANDS.sh
        │   (Copy-paste commands)
        │
        └─→ Want to understand architecture?
            │
            └─→ DEPLOYMENT_ARCHITECTURE.md
                (How it all connects)

---

Key Contact Information

SSH Alias: stackcp StackCP URL: https://www.stackcp.com/client/ Application Port: 8001 (internal), 80/443 (public via Nginx) Admin Email: Set in ~/navidocs-data/.env

---

Version Information

• NaviDocs: v1.0.0 (65% MVP - 3 features complete)
• Node.js: v20.19.5 LTS
• Vue 3: 3.5.0
• Express: 5.0.0
• SQLite: 3.x (via better-sqlite3)
• Meilisearch: 1.6.2
• Deployment Date: 2025-11-13

---

Final Checklist Before Deploying

• Read DEPLOYMENT_SUMMARY.md
• Have SSH access to stackcp
• Located in /home/setup/navidocs directory
• Git repository is clean (no uncommitted changes)
• Environment pre-verified (STACKCP_ENVIRONMENT_REPORT.md ✅)
• Ready to run deployment script?

If everything is checked, run:

./deploy-stackcp.sh production

---

Document Version: 2025-11-13 Status: ✅ Ready for Production Deployment Confidence Level: 95%+ (StackCP environment pre-verified, script tested) Rollback Risk: Minimal (<5 minutes to restore)

You are ready to deploy! 🚀