[Improvement] Local Development Setup Documentation (especially for Windows)

[Kalpana-chavhan]

Description:

The current local development setup instructions can be confusing for new contributors, particularly on Windows. Many contributors report difficulties with installing dependencies, resolving build errors, and understanding the correct tooling setup (Node/Yarn/MongoDB/Meteor) when trying to run Rocket.Chat locally.

What could be improved:

1. Add a clear Windows-verified step-by-step setup guide (including versions and required tooling).

2. Add a troubleshooting section for common errors during dependency installation and build steps.

3. Clarify when to use Docker vs native Meteor setup.

4. Include example .env setup and common fixes for build failures.

Why this matters:

A better onboarding experience will reduce setup issues for first-time contributors and improve contributor retention.

I am willing to:

1. Implement documentation changes

2. Test on Windows 10/11

3. Iterate based on maintainer feedback

4. Add screenshots or short gifs if needed

( This is being raised as a clarification / improvement request.
If a detailed and up-to-date contribution guide for local setup (especially for Windows) already exists, please confirm and point to it. )

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[Kalpana-chavhan]

I tried setting up Rocket.Chat locally on Windows by following the repository structure and existing Docker Compose files.

The docker-compose-ci.yml and docker-compose-local.yml files appear to be CI / deployment-oriented and depend on environment variables such as LOWERCASE_REPOSITORY, DOCKER_TAG, TRANSPORTER, and enterprise services that are not available in a local contributor setup. Running these files locally results in missing configuration errors and invalid image references.

I was able to confirm that the recommended way for contributors is using the Meteor-based development setup (with MongoDB), not Docker Compose. However, this distinction is not clearly documented in the repository, which can be confusing for first-time contributors—especially on Windows.

Please let me know if a local setup guide already exists in another location. If not, I’d be happy to add clear Windows-focused documentation explaining the correct local development workflow and explicitly clarifying the purpose of the existing Docker Compose files

[smirk-dev]

Great issue! I'd like to contribute to this documentation improvement for Windows local development setup. Here's my comprehensive approach:

1. Analysis of Current State:

• Identify all existing documentation scattered across CONTRIBUTING.md, README.md, and dev guide
• Document the actual working setup (Meteor-based vs Docker-based confusion)
• Survey common issues faced by Windows developers

2. New Documentation Structure:

A. Windows Setup Guide (docs/windows-setup.md):

• Prerequisites section:

  • Node.js version (specify exact versions like 18.x, 20.x)
  • Yarn or npm (recommendation with version)
  • MongoDB version & installation for Windows
  • Git configuration for line endings (CRLF vs LF)
  • Visual Studio Build Tools (if needed for native modules)

• Step-by-step installation:

  1. Clone repository
  2. Install dependencies (yarn install)
  3. MongoDB setup & verification
  4. Environment configuration (.env template)
  5. Running development server (meteor or npm start)
  6. Accessing local instance (http://localhost:3000)

B. Troubleshooting Section:

• Module not found errors (solution: delete node_modules + reinstall)
• MongoDB connection issues on Windows (path handling, service status)
• Build failures during yarn install (VS Build Tools requirements)
• Port 3000 already in use (solution: change PORT in .env)
• Windows line ending issues (git config core.autocrlf=false)
• WSL2 vs Native setup comparison

C. Docker vs Meteor Comparison:
Clear table explaining when to use Docker vs native Meteor setup

3. Implementation Plan:

• Create /docs/windows-setup.md with complete guide
• Update CONTRIBUTING.md to reference Windows guide
• Include .env.example with Windows-specific comments
• Add troubleshooting link in README
• Test guide on Windows 10/11 (WSL2 and native)

4. Quality Assurance:

• Test each step on fresh Windows VM
• Screenshot-based walkthrough for key steps
• Version verification commands
• Gather feedback from Windows users

I'm ready to start implementing this and welcome any guidance from maintainers!