navidocs/PORT_ALLOCATION.md

NaviDocs Port Allocation Strategy

Date: 2025-10-19 Purpose: Avoid port conflicts with other projects (FastFile, frank-ai, etc.) Constraint: DO NOT use ports 3000-5500 (reserved for other projects)

---

Port Allocation

NaviDocs Ports (NEW)

Service	Old Port	New Port	Reason
Backend API	3001	8001	Outside 3000-5500 range, common for APIs
Frontend Dev	5173	8080	Outside 3000-5500 range, standard web port

External Services (UNCHANGED)

Service	Port	Status	Notes
Meilisearch	7700	✅ Keep	Already outside restricted range
Redis	6379	✅ Keep	Already outside restricted range
Gitea	4000	✅ Keep	Explicitly requested to keep

StackCP Test Ports

Service	Old Port	New Port	Reason
Test Server	3333	8333	Outside 3000-5500 range

---

Port Range Strategy

Avoided Ranges

• 3000-5500: Reserved for other projects (FastFile, frank-ai, etc.)

Safe Ranges for NaviDocs

• 8000-8999: Web services and APIs (chosen for NaviDocs)
• 9000-9999: Alternative if 8000s conflict
• 6000-6999: Database and cache services (Redis already uses 6379)
• 7000-7999: Search and indexing services (Meilisearch already uses 7700)

---

Changes Required

Configuration Files

1. server/.env

   • PORT=3001 → PORT=8001

2. client/vite.config.js

   • port: 5173 → port: 8080
   • target: 'http://localhost:3001' → target: 'http://localhost:8001'

Documentation Files (24 files)

Files containing port references that need updating:

Root Documentation:

1. README.md - Frontend port 5173 → 8080
2. QUICKSTART.md - Backend port references
3. TEST_RESULTS.md - Backend 3001 → 8001
4. BUILD_COMPLETE.md - Frontend 5173 → 8080
5. SERVICES_STATUS.md - Both ports
6. SESSION_STATUS.md - Both ports
7. NAVIDOCS_HANDOVER.md - Both ports
8. IMPLEMENTATION_COMPLETE.md - Backend 3001 → 8001
9. GOOGLE_DRIVE_OCR_QUICKSTART.md - Backend 3001 → 8001
10. OCR_PIPELINE_SETUP.md - Redis port (keep 6379)

StackCP Documentation: 11. STACKCP_EVALUATION_REPORT.md - Backend 3001 → 8001, test 3333 → 8333 12. STACKCP_VERIFICATION_SUMMARY.md - Test 3333 → 8333 13. STACKCP_ARCHITECTURE_ANALYSIS.md - Backend 3001 → 8001 14. docs/DEPLOYMENT_STACKCP.md - Backend 3001 → 8001 15. docs/STACKCP_QUICKSTART.md - Backend 3001 → 8001

Server Documentation: 16. server/API_SUMMARY.md - Backend 3001 → 8001 17. server/routes/README.md - Backend 3001 → 8001 18. server/services/README.md - Redis port (keep 6379) 19. server/workers/README.md - Redis port (keep 6379)

Config Examples: 20. server/.env.example - Backend 3001 → 8001

---

URL Changes Summary

Development URLs

OLD:

• Backend API: http://localhost:3001
• Frontend: http://localhost:5173 or http://localhost:5174
• Health Check: http://localhost:3001/health

NEW:

• Backend API: http://localhost:8001
• Frontend: http://localhost:8080
• Health Check: http://localhost:8001/health

Production/StackCP URLs

OLD:

• Backend: http://127.0.0.1:3001

NEW:

• Backend: http://127.0.0.1:8001

---

Verification Checklist

After applying changes, verify:

• Server starts on port 8001: cd server && node index.js
• Frontend starts on port 8080: cd client && npm run dev
• Vite proxy works: Visit http://localhost:8080 and test API calls
• No port conflicts: sudo lsof -i :8001 and sudo lsof -i :8080 show only NaviDocs
• Health check works: curl http://localhost:8001/health
• Upload works: curl -X POST http://localhost:8001/api/upload -F "file=@test.pdf"

---

Migration Notes

For Developers

1. Update environment variables:

   cd /home/setup/navidocs/server
   # Edit .env file
   # Change PORT=3001 to PORT=8001
   

2. No code changes needed - ports are configured via environment variables

3. Restart services:

   # Stop old services if running
   pkill -f "node.*index.js"
   pkill -f "vite"
   
   # Start with new ports
   cd /home/setup/navidocs/server
   node index.js  # Will use port 8001
   
   cd /home/setup/navidocs/client
   npm run dev  # Will use port 8080
   

For Documentation Updates

Use find-and-replace:

• localhost:3001 → localhost:8001
• 127.0.0.1:3001 → 127.0.0.1:8001
• localhost:5173 → localhost:8080
• localhost:5174 → localhost:8080
• :3333 → :8333 (StackCP test server)

DO NOT replace:

• :6379 (Redis)
• :7700 (Meilisearch)
• :4000 (Gitea)

---

Rationale

Why 8001 for Backend?

• Outside restricted range (3000-5500)
• Common for APIs (8000-8999 range)
• Memorable (8001 = "eight thousand one")
• No conflicts with standard services

Why 8080 for Frontend?

• Outside restricted range (3000-5500)
• Standard alternative HTTP port (commonly used for web apps)
• Well-known (8080 is universally recognized)
• No conflicts with common services

---

Future Port Assignments

If NaviDocs needs additional services:

Service	Suggested Port	Range
Monitoring	9001	9000-9999
Metrics	9002	9000-9999
Admin Panel	8888	8000-8999
WebSocket	8081	8000-8999

---

Related Projects

Port Allocations (Assumed)

Project	Port Range	Status
FastFile	3000-5500	Active (avoid)
frank-ai/lilian1	3000-5500	Legacy (should be stopped)
NaviDocs	8000-8999	Active (this project)
System Services	Various	Keep (Gitea 4000, Redis 6379, Meilisearch 7700)

---

Emergency Rollback

If the new ports cause issues:

1. Revert .env:

   cd /home/setup/navidocs/server
   # Change PORT=8001 back to PORT=3001
   

2. Revert vite.config.js:

   cd /home/setup/navidocs/client
   # Change port: 8080 back to port: 5173
   # Change target: 'http://localhost:8001' back to 'http://localhost:3001'
   

3. Restart services

4. File an issue documenting the conflict

---

Status: Ready for implementation Impact: Low (environment variable changes only) Risk: Minimal (easy rollback) Timeline: 15-30 minutes for full migration

---

Document Version: 1.0 Last Updated: 2025-10-19 Author: Claude Code