greatbody
/
freeCodeCamp
mirror of https://github.com/freeCodeCamp/freeCodeCamp.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

feat: added npm ci, clone depth, cleanup

pull/35752/head
Christopher McCormack 2019-03-14 21:03:04 -07:00 committed by mrugesh mohapatra
parent ade9475443
commit e95d350bc3
1 changed files with 113 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

231
docs/how-to-setup-freecodecamp-locally.md
View File

@ -27,13 +27,13 @@ Once you have the prerequisites installed, you need to prepare your development
#### Follow these steps to get your development environment ready:
1. Install [Git](https://git-scm.com/) or your favorite Git client, if you haven't already. Update to the latest version, the one that came bundled with your OS may be outdated.
1. Install [Git](https://git-scm.com/) or your favorite Git client, if you haven't already. Update to the latest version; the version that came bundled with your OS may be outdated.
2. (Optional but recommended) [Setup an SSH Key](https://help.github.com/articles/generating-an-ssh-key/) for GitHub.
3. Install a code editor of your choice.
We highly recommend using [VS Code](https://code.visualstudio.com/) or [Atom](https://atom.io/). These are some great free and open source code editors.
We highly recommend using [VS Code](https://code.visualstudio.com/) or [Atom](https://atom.io/). These are great free and open source code editors.
4. Setup linting for your code editor.
@ -42,73 +42,71 @@ Once you have the prerequisites installed, you need to prepare your development
> Please do not ignore any linting errors. They are meant to **help** you and to ensure a clean and simple code base.
## Clone your copy of freeCodeCamp
['Cloning'](https://help.github.com/articles/cloning-a-repository/) is a step where you **download** a copy of a repository that is either owned by you or someone else from a `remote` location. In your case, this remote location is your `fork` of freeCodeCamp's repository, that should be available at `https://github.com/YOUR_USER_NAME/freeCodeCamp`.
['Cloning'](https://help.github.com/articles/cloning-a-repository/) is where you **download** a copy of a repository from a `remote` location that is either owned by you or by someone else. In your case, this remote location is your `fork` of freeCodeCamp's repository that should be available at `https://github.com/YOUR_USER_NAME/freeCodeCamp`.
Run these commands on your local machine:
1. Open a Terminal / Command Prompt / Bash Shell in your projects directory
1. Open a Terminal / Command Prompt / Shell in your projects directory
_i.e.: `/yourprojectdirectory/`_
_i.e.: `/yourprojectsdirectory/`_
2. Clone your fork of freeCodeCamp, replacing `YOUR_USER_NAME` with your GitHub Username
```shell
git clone https://github.com/YOUR_USER_NAME/freeCodeCamp.git
```sh
git clone --depth=1 https://github.com/YOUR_USER_NAME/freeCodeCamp.git
```
This will download the entire freeCodeCamp repository to your projects directory.
## Setup a `upstream` to the main repository
Note: `--depth=1` creates a shallow clone of your fork, with only the most recent history/commit.
## Setup an `upstream` to the main repository
Now that you have downloaded a copy of your fork, you will need to setup an `upstream`.
As mentioned earlier, the main repository at `https://github.com/freeCodeCamp/freeCodeCamp` is often referred to as `upstream` repository. Your fork at `https://github.com/YOUR_USER_NAME/freeCodeCamp` is often referred to as `origin` repository.
As mentioned earlier, the main repository at `https://github.com/freeCodeCamp/freeCodeCamp` is often referred to as the `upstream` repository. Your fork at `https://github.com/YOUR_USER_NAME/freeCodeCamp` is often referred to as the `origin` repository.
You need to point your local clone to the `upstream` in addition to the `origin`. This is so that you can sync changes from the main repository. This way you do not have to go through forking and cloning again and again.
You need a reference from your local clone to the `upstream` repository in addition to the `origin` repository. This is so that you can sync changes from the main repository without the requirement of forking and cloning repeatedly.
1. Change directory to the new freeCodeCamp directory:
```shell
```sh
cd freeCodeCamp
```
2. Add a remote to the main freeCodeCamp repository:
2. Add a remote reference to the main freeCodeCamp repository:
```shell
```sh
git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git
```
3. Check the configuration looks good to you:
3. Ensure the configuration looks correct:
```shell
git remote -v
```sh
git remote -v
```
The output should be something like below:
The output should look something like below:
```shell
origin https://github.com/YOUR_USER_NAME/freeCodeCamp.git (fetch)
origin https://github.com/YOUR_USER_NAME/freeCodeCamp.git (push)
upstream https://github.com/freeCodeCamp/freeCodeCamp.git (fetch)
upstream https://github.com/freeCodeCamp/freeCodeCamp.git (push)
```sh
origin https://github.com/YOUR_USER_NAME/freeCodeCamp.git (fetch)
origin https://github.com/YOUR_USER_NAME/freeCodeCamp.git (push)
upstream https://github.com/freeCodeCamp/freeCodeCamp.git (fetch)
upstream https://github.com/freeCodeCamp/freeCodeCamp.git (push)
```
## Running freeCodeCamp locally on your machine
Now that you have a local copy of freeCodeCamp, you can follow these instructions to run it locally. This will allow you to:
Now that you have a local copy of freeCodeCamp, you can follow these instructions to get it running locally. This will help you to:
- Preview edits to pages as it would appear on the learning platform.
- Preview edits to pages as they would appear on the learning platform.
- Work on UI related issues and enhancements.
- Debug and fix issues in the application servers and client apps.
- Debug and fix issues with the application servers and client apps.
You can skip running freeCodeCamp locally, if you are just editing files, doing a `rebase` or resolving `merge` conflicts. You can always return to this part of the instructions later.
You can skip running freeCodeCamp locally if you are simply editing files, performing a `rebase` or resolving `merge` conflicts. You can always return to this part of the instructions later.
[Skip running freeCodeCamp locally](#making-changes-to-your-clone-of-freecodecamp-locally)
### Installing prerequisites
Start by installing these prerequisite software.
Start by installing the prerequisite software:
| Prerequisite | Version | Notes |
| --------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -117,33 +115,34 @@ Start by installing these prerequisite software.
| npm (comes bundled with Node) | `6.x` | Does not have LTS releases, we use the version bundled with Node LTS |
#### Important:
We highly recommend updating to the latest stable releases a.k.a Long Term Support (LTS) versions of the above.
If Node.js or MongoDB is already installed on your machine, run the following commands to validate the versions:
We highly recommend updating to the latest stable releases of the software above, also known as Long Term Support (LTS) releases.
If Node.js and MongoDB are already installed on your machine, run the following commands to validate the versions:
```shell
```sh
node -v
mongo --version
npm -v
```
> If you have a different version, please install the recommended version. We can support installation issues for recommended versions only.
> If you have a different version, please install the recommended version. We can only support installation issues for recommended versions.
#### Note to Windows users:
Make sure the command line tool (Cmd, PowerShell or Git Bash for Windows, etc.) you use has the correct user privileges. If possible, you should launch the tool with Administrator's privilege. On windows, you should be able to launch a tool by right clicking it and selecting `Launch as an Administrator`.
Make sure the command line tool you use (Cmd, PowerShell or Git Bash for Windows, etc.) has the correct user privileges. If possible, you should launch the tool with Administrator's privilege. On windows, you should be able to launch as administrator by right clicking the application and selecting `Launch as an Administrator`.
#### I am having issues with installing the recommended prerequisites. What should I do?
We regularly develop on popular and latest operating systems like macOS 10.12 or later, Ubuntu 16.04 or later and Windows 10. Its recommended to lookup your specific issue on resources like: Google, Stack Overflow or Stack Exchange. Chances are that someone has faced the same issue and there is already an answer to your specific query.
We regularly develop on the latest or most popular operating systems like macOS 10.12 or later, Ubuntu 16.04 or later and Windows 10. It is recommended to lookup your specific issue on resources such as Google, Stack Overflow and Stack Exchange. Chances are good that someone has faced the same issue and there is already an answer to your specific query.
If you are on a different OS, and/or are still running into issues, reach out to [contributors community on our public forum](https://www.freeCodeCamp.org/c/contributors) or the [contributor's chat room](https://gitter.im/freeCodeCamp/Contributors).
If you are on a different OS and/or are still running into issues, reach out to the [contributors community on our public forum](https://www.freeCodeCamp.org/c/contributors) or the [contributor's chat room](https://gitter.im/freeCodeCamp/Contributors).
Please avoid creating GitHub issues for pre-requisite issues. They are out of the scope of this project.
Please avoid creating GitHub issues for prerequisite issues. They are out of the scope of this project.
### Installing dependencies
### Configuring dependencies
First you need to add the private environment variables (API Keys):
#### Step 1: Setup the environment variable file
The default API keys and environment variables are stored in the file `sample.env`. This file needs to be copied to a new file named `.env` that is accessed dynamically during the installation step.
```shell
# Create a copy of the "sample.env" and name it as ".env".
```sh
# Create a copy of the "sample.env" and name it ".env".
# Populate it with the necessary API keys and secrets:
# macOS / Linux
@ -153,104 +152,94 @@ cp sample.env .env
copy sample.env .env
```
Then you have to install the dependencies required for the application to startup.
The keys in the `.env` file are *not* required to be changed to run the app locally. You can leave the default values copied over from `sample.env` as-is.
```shell
Keep in mind if you want to use additional services, you'll have to get your own API keys for those services and edit those entries accordingly in the `.env` file.
#### Step 2: Install dependencies
This step will install the dependencies required for the application to run:
```sh
# Install NPM dependencies
npm install
npm ci
```
The keys are not required to be changed, to run the app locally. You can leave the default values from the `sample.env` as is.
#### Step 3: Start MongoDB
Unless you have MongoDB running in a setup different than the default, the URL stored as the `MONGOHQ_URL` value in the `.env` file should work fine. If you are using a custom configuration, modify this value as needed.
Before you can run the application locally, you will need to start the MongoDB service:
Next, let's bootstrap the various services, i.e. the api-server, the client UI application, etc. You can [learn more about these services in this guide](#).
`MONGOHQ_URL` is the most important one. Unless you have MongoDB running in a setup different than the defaults, the URL in the `sample.env` should work fine.
You can leave the other keys as they are. Keep in mind if you want to use more services you'll have to get your own API keys for those services and edit those entries accordingly in the `.env` file.
### Start MongoDB
You will need to start MongoDB, before you can start the application:
Start the MongoDB server in a separate terminal
Start the MongoDB server in a separate terminal:
- On macOS & Ubuntu:
```shell
```sh
mongod
```
- On Windows, you have to instead specify the full path to the `mongod` binary
- On Windows, you must specify the full path to the `mongod` binary
Make sure to replace `3.6` with the version you have installed
```shell
```sh
"C:\Program Files\MongoDB\Server\3.6\bin\mongod"
```
Make sure to replace `3.6` with the version you have installed
> ProTip:
> You can avoid having to start MongoDB every time, by installing it as a background service.
> You can avoid having to start MongoDB every time by installing it as a background service.
> You can [learn more about it in their documentation for your OS](https://docs.mongodb.com/manual/administration/install-community/)
### Seeding the database
#### Step 4: Seeding the database
Next, let's seed the database. In this step, we run the below command that fills the MongoDB server with some initial data sets that are required by services. This include a few schemas, among other things.
Next, let's seed the database. In this step, we run the below command that will fill the MongoDB server with some initial data-sets that is required by the other services. This include a few schemas, among other things.
```shell
```sh
npm run seed
```
### Start the freeCodeCamp client application and API server
#### Step 5: Start the freeCodeCamp client application and API server
You can now start up the API server and the client applications.
```shell
```sh
npm run develop
```
This single command will fire up all the services, including the API server and the client applications available for you to work on.
Now open a web browser and visit <http://localhost:8000>. If the app loads, congratulations – you're all set.
Once ready, open a web browser and visit <http://localhost:8000>. If the app loads, congratulations – you're all set!
> ProTip:
>
> The API Server serves APIs at `http://localhost:3000`
> The Gatsby app serves the client application at `http://localhost:8000`
Meaning, if you visit <http://localhost:3000/explorer> you should see the APIs that we have.
If you visit <http://localhost:3000/explorer> you should see the available APIs.
Congratulations 🎉! You now have a copy of freeCodeCamp's entire learning platform running on your local machine.
Congratulations 🎉🎉🎉! You now have a copy of freeCodeCamp's entire learning platform running on your local machine.
## How to Sign in when working locally
Your local setup automatically populates a local user in the database. Clicking the `Sign In` button will automatically authenticate you into the local application.
Your local setup automatically populates a local user in the database. Clicking the sign in button will automatically authenticate you into the local application.
However, accessing the user portfolio page is a little tricky. In development, Gatsby takes over serving the client side pages and hence you will get a 404 page for the user portfolio when working locally.
However, accessing the user portfolio page is a little tricky. In development, Gatsby takes over serving the client side pages and hence you will get a `404` page for the user portfolio when working locally.
Simply clicking the `Preview Custom 404 Page` button will forward you to the correct page.
![Image - How to sign in when working locally](https://user-images.githubusercontent.com/1884376/52650951-48922e80-2f11-11e9-9eee-360a25ad28ad.gif)
## Quick commands reference when working locally
[Here is a quick reference](/docs/README.md) to a list of commands that you may need locally from time to time:
[Here is a quick reference](/docs/README.md) to a list of commands that you may occasionally need locally.
## Making changes to your clone of freeCodeCamp locally
Next, you can make changes to files, and commit your changes.
You can now make changes to files and commit your changes to your local clone of your fork.
Follow these steps:
1. Check that you are on the `master` branch
1. Validate that you are on the `master` branch
```shell
```sh
git status
```
You should get an output like this:
```shell
```sh
On branch master
Your branch is up-to-date with 'origin/master'.
@ -259,43 +248,52 @@ Follow these steps:
If you are not on master or your working directory is not clean, resolve any outstanding files/commits and checkout `master`:
```shell
```sh
git checkout master
```
2. Next, you would want to **sync the lastest changes for `master` branch** from the main repository of freeCodeCamp.
2. Sync the latest changes from the freeCodeCamp upstream `master` branch to your local master branch
**Note:** If you have any outstanding pull-request that you made from the `master` branch of your fork previously, you will lose them. You should get it merged by a moderator, prior following this. To avoid this, you should always work on a branch.
**Note:** If you have any outstanding Pull Request that you made from the `master` branch of your fork, you will lose them at the end of this step. You should ensure your pull request is merged by a moderator prior to performing this step. To avoid this scenario, you should *always* work on a branch separate from master.
This step **will sync the latest changes** from the main repository of freeCodeCamp. It is important that you rebase as often as possible, to avoid conflicts later.
This step **will sync the latest changes** from the main repository of freeCodeCamp. It is important that you rebase your branch on top of the latest `upstream/master` as often as possible to avoid conflicts later.
```shell
Update your local copy of the freeCodeCamp upstream repository:
```sh
git fetch upstream
```
Now, you want to do a hard reset with the copy on the freeCodeCamp master:
Hard reset your master branch with the freeCodeCamp master:
```shell
```sh
git reset --hard upstream/master
```
Push this branch back to your origin, to have a clean history on your fork on GitHub:
Push your master branch to your origin to have a clean history on your fork on GitHub:
```shell
```sh
git push origin master --force
```
3. Next, you will have to create a fresh new branch.
You can validate your current master matches the upstream/master by performing a diff:
Working on a separate branch for every single issue, helps you keep your local work copy clean. You should never work on the `master`. This will soil your copy of freeCodeCamp and you may have to start over with a fresh clone or fork.
```sh
git diff upstream/master
```
The resulting output should be empty.
3. Create a fresh new branch
Working on a separate branch for each individual issue helps you keep your local work copy clean. You should never work on the `master`. This will soil your copy of freeCodeCamp and you may have to start over with a fresh clone or fork.
Check that you are on `master` as explained previously, and branch off from there:
```shell
```sh
git checkout -b fix/update-guide-for-xyz
```
Your branch name should start with a `fix/`, `feat/`, etc. Avoid, using issue no.s in branches. Keep them short, meaningful and unique.
Your branch name should start with a `fix/`, `feat/`, `docs/`, etc. Avoid using issue numbers in branches. Keep them short, meaningful and unique.
Some examples of good branch names are:
@ -307,21 +305,21 @@ Follow these steps:
translate/add-spanish-basic-html
```
4. Next, you can work on the editing pages and working on the code in your favorite text editor.
4. Edit pages and work on code in your favorite text editor
5. Once you are happy with the changes you should optionally run freeCodeCamp locally to preview the changes.
5. Once you are happy with the changes you should optionally run freeCodeCamp locally to preview the changes
6. Make sure you fix any errors, and check the formatting of your changes. We have style guide for the Guide articles and Coding challenges.
6. Make sure you fix any errors, and check the formatting of your changes. We have style guides in the [docs](/docs/) section for the Guide articles and Coding challenges
7. Next, check and confirm the files you are updating
7. Check and confirm the files you are updating
```shell
```sh
git status
```
This should show a list of `unstaged` files that you have edited.
```shell
```sh
On branch feat/documentation
Your branch is up to date with 'upstream/feat/documentation'.
@ -336,28 +334,28 @@ Follow these steps:
...
```
8. Stage the changes and make a commit.
8. Stage the changes and make a commit
In this step you should only mark files that you have edited, or added. You can perform a reset, and resolve files that you did not intend to change.
In this step you should only mark files that you have edited or added yourself. You can perform a reset and resolve files that you did not intend to change, if needed.
```shell
```sh
git add path/to/my/changed/file.ext
```
Or, alternatively you can add all the `unstaged` files to the staging area:
```shell
```sh
git add .
```
Only the files that were moved to the staging area will be added when you make a commit.
```shell
```sh
git status
```
Output:
```shell
```sh
On branch feat/documentation
Your branch is up to date with 'upstream/feat/documentation'.
@ -372,7 +370,7 @@ Follow these steps:
Now, you can commit your changes with a short message like so:
```shell
```sh
git commit -m "fix: my short commit message"
```
@ -404,7 +402,7 @@ Follow these steps:
9. If you realise that you need to edit a file or update the commit message after making a commit you can do so after editing the files with:
```shell
```sh
git commit --amend
```
@ -412,25 +410,22 @@ Follow these steps:
10. Next, you can push your changes to your fork.
```shell
```sh
git push origin branch/name-here
```
## Proposing a Pull Request (PR)
After you've committed your changes, check here for [how to open a Pull Request](/docs/how-to-open-a-pull-request.md).
## Getting Help
If you are stuck, and need help, let us know by asking in the ['Contributors' category on our forum](https://www.freecodecamp.org/forum/c/contributors) or the [Contributors chat room](https://gitter.im/FreeCodeCamp/Contributors) on Gitter.
There might be an error in the console of your browser or in Bash / Terminal / Command Line that will help identify the problem.
There might be an error in the console of your browser or in Bash / Terminal / Command Line that will help identify the problem. Provide this error message in your problem description so others can more easily identify the issue and help you find a resolution.
### Troubleshooting
If the app launches but you are encountering errors with the UI itself, for example if fonts are not being loaded or if the code editor is not displaying properly, you may try the following troubleshooting steps at least once:
```shell
```sh
# We use a mono repo and have multiple components (server, client, tools, plugins, etc.)
# Use this command to clean up all dependencies in all of the components
npm run clean