freeCodeCamp
freeCodeCamp copied to clipboard
freeCodeCamp
Article on how to setup freeCodeCamp locally inadvertently gives mongodb server starting instructions twice, leading to confusion
Describe the Issue
Windows users attempting to follow each step outlined in the article https://contribute.freecodecamp.org/#/how-to-setup-freecodecamp-locally will encounter an error on the 2nd mongoDB server startup step because it was already started in an earlier instruction.
The first time mongoDB server is started is in the steps linked from "How to prepare your local machine". The second time is later on in the article in the section called "Step 3: Start MongoDB and seed the database".
The error encountered the second time is: Command 'mongod' not found, but can be installed with: sudo apt install mongodb-server-core
Users may not realize that they had already done all they needed to do for mongodb setup in a prior step leading to confusion.
Affected Page
https://contribute.freecodecamp.org/#/how-to-setup-freecodecamp-locally
Steps to Reproduce
on Windows 10+, follow all the instructions in the article (https://contribute.freecodecamp.org/#/how-to-setup-freecodecamp-locally) including the ones mentioned in (https://contribute.freecodecamp.org/#/how-to-setup-wsl) which is linked from the first article.
Further Details: Readers encounter the first section "How to prepare your local machine" where it says: "We also support Windows 10 via WSL2, which you can prepare by reading this guide." The link given goes to an article "Set up freeCodeCamp on Windows Subsystem for Linux (WSL)" and has multiple steps within, which include "Start the MongoDB service at port 27017..." with accompanying instructions.
Once finished following the steps provided in the second article, we return back to the first reference article to continue the remaining steps following the section "How to prepare.." And as we do so, we encounter again the instruction to start the MongoDB (Step 3: Start MongoDB and see the database). Blindly following this step then we see this error: "Command 'mongod' not found, but can be installed with: sudo apt install mongodb-server-core"
And there arises the confusion. Didn't we install it already? Maybe this is something else? So we go ahead and install it again. Leading to further errors down this road such as the one mentioned in issue #45784
Recommended fix or suggestions
Clarification needs to be given to explain that the 2nd time we are told to start it with mongod command is only needed if it hadn't already been started successfully before (perhaps with a suggestion to check the service mongodb://localhost:27017 first).
Screenshots
No response
Is it this whole section that needs a disclaimer that just says something like:
if you have already ran the MongoDB command, you can skip past this step and continue following the guide.
Would you like to typo up the best disclaimer you think would work best and then I can implement it.
I do not see a bug here. There are specific instructions for working with WSL, and there are specific instructions for locally setting freeCodeCamp up.
Blindly following this step then we see this error:
Campers should not blindly follow any documentation. Let alone one that has you install software on your local pc. This is the issue here.
I just think a lot of newcomers not necessarily are going through blindly but they are only because they don't understand everything. If we add one line of a warning, those readers following with not a great understanding of what they are really doing will not run into this error.
Even if it helps 3 people I think its still a good addition.
Even if it helps 3 people I think its still a good addition.
It will help a lot more than 3 I assure you. (check discord for all previous run-ins, though they usually work around by installing mongodb again with the command from the error then get another error on seeding step etc)
Yes I think your suggestion to add a disclaimer above the box showing the mongod command would work perfectly.
Would you like to typo up the best disclaimer you think would work best and then I can implement it.
Sure, how about this: On Windows 10+, skip this step if the mongoDB service is already running. Confirm this by checking that you can reach http://localhost:27017/ .
Is this issue now open for help? I wasn't sure what additional approval was needed, and I would love to get my first contribution on freeCodeCamp!
Is this issue now open for help? I wasn't sure what additional approval was needed, and I would love to get my first contribution on freeCodeCamp!
I would argue that this is a change worth making because people don't always read the documentation thoroughly. I know that this is on them at the end of the day, but I think if we can add a short disclaimer that could help someone, even if it's one person, it's a change worth making.
This issue has not been active for about 20 days now so I would say if you agree, create a pull request and make these changes. We can discuss further there if needed.
An issue with the https://github.com/freeCodeCamp/freeCodeCamp/labels/help%20wanted or https://github.com/freeCodeCamp/freeCodeCamp/labels/first%20timers%20only label is open for contribution. The first comprehensive PR created will be reviewed and merged. We typically do not assign issues to anyone other than long-time contributors.
If you would like to contribute, and have not read the contributors docs, please do so here: https://contribute.freecodecamp.org/#/
If you have any issues with contributing, be sure to join us on the contributors channel, or on the contributors sub-forum