Skip to content

fix: improve Cumulus guide clarity and technical accuracy

Mats Lock requested to merge fix/update-cumulus-documentation into main

📋 Summary

This MR improves the Cumulus machine setup guide with several technical clarifications and user experience enhancements based on testing and feedback.

🔧 Key Improvements

SSH and GitLab Configuration:

  • Clarified SSH key configuration for GitLab access on Cumulus machines
  • Added troubleshooting section for SSH permission issues
  • Improved clone-move-fix workflow for repository access
  • Enhanced explanation of sudo vs user context for SSH operations

PM2 Process Management:

  • Renamed configuration file to ecosystem.config.yml (following PM2 conventions)
  • Moved PM2 startup configuration to main workflow (no longer optional)
  • Added detailed explanation of boot persistence importance
  • Improved startup script generation instructions with warnings

nginx Configuration Enhancements:

  • Added nginx configuration testing after Certbot certificate installation
  • Included HTTP/2 benefits explanation in server configuration
  • Added file structure diagrams for better student comprehension
  • Improved modular configuration approach documentation

Windows User Support:

  • Added Windows Subsystem for Linux (WSL) recommendation
  • Enhanced SSH client installation options
  • Improved cross-platform compatibility instructions

Technical Clarifications:

  • Explained exec_mode: "fork" vs cluster mode in PM2
  • Clarified why direct script execution is preferred over npm start
  • Added comprehensive troubleshooting sections
  • Improved file permission explanations

📚 Documentation Structure

Enhanced sections:

  • Step 8: Added nginx restart after certificate installation
  • Step 12: Improved GitLab SSH setup and clone workflow
  • Step 13: Elevated PM2 startup configuration to critical status
  • Added file system structure diagrams throughout

✅ Quality Improvements

  • Reduced confusion: Clearer separation between local and remote operations
  • Better error handling: Added troubleshooting for common SSH and permission issues
  • Production focus: Emphasized critical configurations for server reliability
  • Cross-platform support: Improved instructions for different operating systems
  • Technical accuracy: Corrected explanations of user contexts and permissions

🎯 Impact

These changes address common student confusion points and ensure the guide follows best practices for production server deployment. The improvements make the tutorial more robust and reduce support overhead.

Merge request reports