navidocs/STACKCP_DEBATE_BRIEF.md

# StackCP Deployment Debate Brief

**For**: Security Expert, OCI Architect, Tech Lead Discussion
**Subject**: NaviDocs Deployment on StackCP Shared Hosting
**Date**: 2025-10-19
**Status**: Awaiting technical consensus

---

## The Situation

NaviDocs was designed with standard deployment assumptions (local services, normal filesystem permissions, VPS-like environment). Recent evaluation of StackCP (20i shared hosting) revealed **critical constraints** that break these assumptions.

**Key Discovery**: Only `/tmp` directory has executable permissions; home directory is mounted `noexec`.

---

## Critical Constraints Summary

### 1. File System Constraints
- **Executable location**: ONLY `/tmp/` (all code, native modules)
- **Persistent storage**: `~/navidocs/` (database, uploads, logs, config)
- **Persistence risk**: `/tmp` may be cleared on reboot
- **Security risk**: `/tmp` is readable by other StackCP users

### 2. Service Constraints
- **No local Redis**: Must use Redis Cloud (free 30MB tier)
- **No local Tesseract**: Must use Google Cloud Vision API (free 1K pages/month)
- **Meilisearch**: Already running on server (bonus)
- **Process manager**: StackCP Node.js Manager (GUI-based) OR manual (nohup)

### 3. Development Constraints
- **npm execution**: Must use `/tmp/node /path/to/npm-cli.js` wrapper
- **Native modules**: Must compile in `/tmp` (better-sqlite3, bcrypt)
- **Path configuration**: All paths must be environment-configurable
- **Deployment**: Code from Git to `/tmp`, data backups to `~`

---

## Architectural Impact

### Code Changes Required (2-3 days)
1. Centralized path configuration (`server/config/paths.js`)
2. Update all file operations to use configurable paths
3. Environment detection (local vs StackCP)
4. Startup validation (fail fast if paths wrong)

### Operational Changes Required (1-2 days)
1. Daily checkpoint script (`/tmp` → `~/code-checkpoint/`)
2. Health check script (detect `/tmp` code loss, auto-recover)
3. Data backup script (SQLite + uploads, NOT code)
4. Restore procedure (Git → `/tmp`, backups → data)

### Documentation Changes Required (1-2 days)
1. Rewrite QUICKSTART.md (split local vs StackCP)
2. Update ARCHITECTURE-SUMMARY.md (add deployment constraints)
3. Revise 2-week-launch-plan.md (StackCP-specific steps)
4. Create deployment runbook

**Total Effort**: 5-7 days focused work

---

## Key Questions for Debate

### For Security Expert:

1. **Risk Assessment**: `/tmp/navidocs` is readable by other StackCP users
   - Threat: Source code exposure (including algorithm logic)
   - Threat: `.env` symlink in `/tmp` could expose secrets
   - Mitigation: Keep secrets in `~/navidocs/.env` (noexec but protected), symlink carefully
   - **Question**: Is this acceptable risk for MVP, or blocker requiring VPS migration?

2. **External Service Security**: Redis Cloud + Google Vision API
   - Benefit: Managed services, professional security
   - Risk: Network dependency, potential service compromise
   - **Question**: Does cloud-first approach meet security requirements?

3. **Code Integrity**: `/tmp` persistence risk
   - Risk: Code could be cleared, replaced, or tampered with
   - Mitigation: Daily checksums, auto-recovery from Git
   - **Question**: Can we trust code integrity in `/tmp`?

### For OCI Architect:

1. **Container Alternative**: Should we abandon StackCP for containerized deployment?
   - Option A: Docker on StackCP (if supported)
   - Option B: Migrate to container hosting (Fly.io, Railway, etc.)
   - Option C: DigitalOcean App Platform (container-based)
   - **Question**: Is the StackCP complexity worth it vs. $5/month VPS?

2. **Architecture Portability**: How to maintain deployment flexibility?
   - Current: Local dev, StackCP prod
   - Future: VPS, Kubernetes, serverless?
   - **Question**: Should we design for StackCP OR design agnostic with StackCP adapter?

3. **Operational Complexity**: Is this maintainable long-term?
   - Custom scripts: checkpoint, health checks, recovery
   - Two-location deployment: `/tmp` + `~`
   - Manual monitoring: /tmp persistence
   - **Question**: Does this operational overhead scale?

### For Tech Lead:

1. **Developer Experience**: How does this affect development workflow?
   - Local dev: Standard npm, relative paths
   - StackCP deploy: Wrapper scripts, absolute paths, manual recovery
   - **Question**: Can we maintain DX while supporting StackCP?

2. **Testing Strategy**: How to test StackCP-specific scenarios?
   - Unit tests: Path configuration
   - Integration tests: Checkpoint/restore
   - E2E tests: Deployment on fresh StackCP account
   - **Question**: What's the minimum viable test coverage?

3. **Rollout Plan**: How to phase this in?
   - Phase 1: Core path configuration (blocks everything else)
   - Phase 2: Operational scripts (enables deployment)
   - Phase 3: Documentation (enables users)
   - Phase 4: Beta test on StackCP (validates assumptions)
   - **Question**: Can we ship without full StackCP support first?

---

## Three Paths Forward

### Path A: Full StackCP Adaptation (5-7 days)
**Pros**:
- Use existing hosting (no new costs)
- Learn shared hosting constraints (educational)
- Meilisearch already running (bonus)

**Cons**:
- Significant architecture changes
- Operational complexity (checkpoint scripts, monitoring)
- Security risks (`/tmp` exposure, external services)
- Technical debt (StackCP-specific code)

**Recommendation**: Only if StackCP hosting is **must-have** constraint

---

### Path B: Hybrid Approach (3-4 days)
**Pros**:
- Design path-agnostic architecture (good practice anyway)
- Support StackCP as deployment option (not primary)
- Maintain standard development workflow
- Easy migration to VPS later

**Cons**:
- Still requires StackCP scripts and documentation
- Testing complexity (multiple environments)
- Partial investment in StackCP-specific tooling

**Recommendation**: Best balance of flexibility and investment

---

### Path C: Abandon StackCP, Use VPS (1 day)
**Pros**:
- Standard deployment (PM2, systemd, local services)
- Better security (isolated environment)
- Simpler operations (single code location)
- Lower technical debt
- Easier to document and support

**Cons**:
- Additional cost ($5-10/month DigitalOcean/Linode)
- Need to manage VPS (updates, security patches)
- Lose Meilisearch bonus (need to install)

**Recommendation**: Simplest path, industry-standard approach

---

## Cost Comparison

### StackCP Deployment (Path A/B)
```
StackCP Hosting:         $X/month (already paying)
Redis Cloud:             $0 (free 30MB tier)
Google Vision API:       $0 (free 1K pages/month)
Development time:        5-7 days (Path A) or 3-4 days (Path B)
Operational overhead:    Ongoing (monitoring, checkpoints)
---
Total new cost:          $0/month
Total time investment:   3-7 days + ongoing maintenance
```

### VPS Deployment (Path C)
```
DigitalOcean Droplet:    $6/month (1GB RAM, 25GB SSD)
  OR Linode Nanode:      $5/month (1GB RAM, 25GB SSD)
Development time:        1 day (standard deployment)
Operational overhead:    Standard (systemd, cron backups)
---
Total new cost:          $5-6/month
Total time investment:   1 day + standard VPS maintenance
```

### Real-World Scenarios

**Small marina (50 manuals/month)**:
- StackCP: $0 new cost, 5-7 days setup + ongoing overhead
- VPS: $6/month, 1 day setup, minimal overhead

**Medium marina (500 manuals/month)**:
- StackCP: May exceed free tiers → $6-10/month for Redis + Vision
- VPS: $6/month, can run all services locally

**Verdict**: VPS is simpler and potentially cheaper at scale

---

## Security Risk Matrix

| Risk | StackCP | VPS |
|------|---------|-----|
| Source code exposure | **HIGH** (`/tmp` readable) | **LOW** (isolated) |
| Secrets exposure | **MEDIUM** (careful symlinks) | **LOW** (standard perms) |
| External service compromise | **MEDIUM** (Redis/Google Cloud) | **LOW** (local services) |
| Code tampering | **MEDIUM** (`/tmp` volatile) | **LOW** (standard deploy) |
| Data breach | **LOW** (same in both) | **LOW** (same in both) |
| DDoS vulnerability | **LOW** (shared IP protected) | **MEDIUM** (direct exposure) |

**Overall Security**: VPS is more secure for production data

---

## Technical Debt Analysis

### StackCP-Specific Technical Debt
1. **Path configuration abstraction** (useful everywhere, low debt)
2. **Checkpoint/recovery scripts** (StackCP-only, medium debt)
3. **npm wrapper scripts** (StackCP-only, low debt)
4. **Dual-location deployment logic** (StackCP-only, high debt)
5. **Health checks for /tmp loss** (StackCP-only, medium debt)
6. **StackCP-specific documentation** (maintenance burden)

**Debt Score**: Medium-High (some useful, some waste)

### VPS Technical Debt
1. **Standard systemd services** (industry standard, no debt)
2. **Standard backup scripts** (reusable, no debt)
3. **PM2 process management** (industry standard, no debt)
4. **VPS-specific documentation** (broadly useful, low debt)

**Debt Score**: Low (standard practices)

---

## Recommendations for Debate

### Tech Lead Perspective

**Recommended Path**: **Path C (VPS)** for production, **Path B (Hybrid)** if StackCP is required

**Reasoning**:
1. **Developer Experience**: VPS maintains standard workflow, StackCP requires special handling
2. **Time Investment**: 1 day (VPS) vs 5-7 days (StackCP) for same functionality
3. **Operational Complexity**: VPS is industry-standard, StackCP requires custom tooling
4. **Technical Debt**: VPS has minimal debt, StackCP accumulates StackCP-specific code
5. **Security**: VPS provides better isolation and code integrity

**Compromise Position** (if StackCP is required):
- Implement **Path B (Hybrid)**: Path-agnostic core, StackCP adapter
- Design for portability (easy VPS migration later)
- Document StackCP as "advanced deployment option"
- Use StackCP for MVP, migrate to VPS if successful

### Security Considerations

**Red Flags for StackCP**:
1. `/tmp` code exposure to other users
2. Code integrity concerns (volatility, tampering)
3. External service dependencies (attack surface)

**Acceptable if**:
- No sensitive algorithms in code (open source anyway?)
- Secrets properly protected in `~/navidocs/.env`
- Health checks validate code integrity on startup
- External services use strong authentication

### OCI Considerations

**StackCP is NOT container-friendly**:
- No Docker support on shared hosting
- Custom deployment model doesn't align with container best practices
- Better alternatives: Fly.io ($0-5/month), Railway ($5/month), Render ($7/month)

**If containerization is a goal**: Skip StackCP entirely, use container platform from day 1

---

## Decision Framework

### Choose StackCP IF:
- [ ] Already paying for StackCP hosting (sunk cost)
- [ ] Cannot afford $5/month VPS (budget constraint)
- [ ] Educational value of shared hosting constraints (learning)
- [ ] Willing to accept security tradeoffs (low-risk data)
- [ ] Have 5-7 days to invest in adaptation

### Choose VPS IF:
- [ ] Production security is priority (sensitive data)
- [ ] Want standard deployment model (less complexity)
- [ ] Need local services (Redis, Tesseract)
- [ ] Future scalability important (easy horizontal scaling)
- [ ] Want to ship MVP quickly (1 day vs 5-7 days)

### Choose Container Platform IF:
- [ ] Want modern deployment model (Dockerfile, Git push deploy)
- [ ] Need auto-scaling (traffic spikes)
- [ ] Multi-region deployment (future)
- [ ] CI/CD integration (GitHub Actions → auto-deploy)
- [ ] Budget allows ($5-10/month)

---

## Questions for Group Decision

1. **Is StackCP hosting a hard requirement, or can we consider VPS?**
   - If required: Why? (cost, existing account, other constraints?)
   - If flexible: What's the decision criteria?

2. **What's the risk tolerance for `/tmp` code exposure?**
   - Is NaviDocs code open source anyway? (if yes, exposure is lower risk)
   - Are there proprietary algorithms that must be protected?

3. **What's the timeline for MVP launch?**
   - If urgent: VPS is faster (1 day vs 5-7 days)
   - If flexible: StackCP adaptation is feasible

4. **What's the long-term vision for deployment?**
   - Single-server: VPS is fine
   - Multi-region: Container platform is better
   - StackCP forever: Full adaptation needed

5. **Who will maintain operational scripts?**
   - If solo dev: VPS is simpler (less to maintain)
   - If team: StackCP complexity is manageable

---

## Proposed Action Items

### Immediate (Before Debate)
- [ ] Verify `/tmp` persistence on StackCP (how often is it cleared?)
- [ ] Test `/tmp` file permissions (can other users read?)
- [ ] Confirm StackCP Node.js Manager capabilities
- [ ] Price check: DigitalOcean vs Linode vs Fly.io vs Railway

### If Choosing StackCP (Path A/B)
- [ ] Implement `server/config/paths.js` (centralized configuration)
- [ ] Create StackCP deployment scripts
- [ ] Write operational scripts (checkpoint, health check, backup)
- [ ] Test on StackCP with dummy app
- [ ] Security review: `.env` protection, code exposure
- [ ] Document StackCP-specific workflows

### If Choosing VPS (Path C)
- [ ] Sign up for VPS provider (DigitalOcean recommended)
- [ ] Write standard deployment script (PM2 + systemd)
- [ ] Install Meilisearch, Redis, Tesseract
- [ ] Deploy NaviDocs with standard workflow
- [ ] Set up backups (daily SQLite + uploads)
- [ ] Document VPS deployment

### If Choosing Container Platform
- [ ] Create Dockerfile for NaviDocs
- [ ] Test locally with Docker Compose
- [ ] Choose platform (Fly.io, Railway, Render)
- [ ] Set up CI/CD (GitHub Actions → auto-deploy)
- [ ] Configure external services (managed Redis, Meilisearch)
- [ ] Document container deployment

---

## Summary for Debate

**Situation**: StackCP has unique constraints that require architectural changes
**Options**: Full StackCP adaptation (5-7 days), Hybrid (3-4 days), VPS (1 day)
**Recommendation**: VPS for production, Hybrid if StackCP required
**Key Decisions Needed**:
1. Is StackCP a hard requirement?
2. What's the security risk tolerance?
3. What's the MVP timeline?
4. What's the long-term deployment vision?

**Next Steps**: Debate, decide path, implement chosen approach

---

**Prepared by**: Tech Lead
**Date**: 2025-10-19
**For Review**: Security Expert, OCI Architect
**Decision Deadline**: Before Phase 1 implementation begins