docs: moved local docker setup into local setup file (#35975)
This commit is contained in:
Christopher McCormack
committed by
mrugesh mohapatra
mrugesh mohapatra
parent
6e8e8e3f18
commit
dbfd1e2a2f
@ -1,7 +1,4 @@
|
||||
# Set up freeCodeCamp locally
|
||||
|
||||
As of 8 March 2019, please consider helping us test our new guide on how to [setup freeCodeCamp locally using Docker](/docs/how-to-setup-freecodecamp-locally-using-docker.md) instead of using this guide. It *should* result in fewer, if not zero, errors but we won't know until enough devs try it.
|
||||
|
||||
Follow these guidelines for getting freeCodeCamp locally on your system. This is highly recommended if you want to contribute regularly.
|
||||
|
||||
Some of the contribution workflows, like previewing pages for the guide or the coding challenges, debugging and fixing bugs in codebase, requires you to have freeCodeCamp running locally.
|
||||
@ -26,7 +23,6 @@ This is essential as it allows you to work on your own copy of freeCodeCamp on G
|
||||
Once you have the prerequisites installed, you need to prepare your development environment. This is common for many development workflows, and you will only need to do this once.
|
||||
|
||||
#### 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 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.
|
||||
@ -105,36 +101,61 @@ You can skip running freeCodeCamp locally if you are simply editing files, perfo
|
||||
|
||||
[Skip running freeCodeCamp locally](#making-changes-to-your-clone-of-freecodecamp-locally)
|
||||
|
||||
There are currently two methods to run freeCodeCamp locally:
|
||||
- Docker (recommended)
|
||||
- Local
|
||||
|
||||
You are required to follow any **one** of the above methods.
|
||||
|
||||
The Docker setup will ideally result in fewer errors during the installation process and aims to have the best developer experience. We use Docker to install and run the additional software dependencies behind the scenes. This should make it hassle-free and consistent experience across most device/OS types.
|
||||
|
||||
If you are having issues using one method, try using the other. If you do run into issues with either method, first perform a web search for your issue and see if it has already been answered. If you cannot find a solution, please search our GitHub [issues](https://github.com/freeCodeCamp/freeCodeCamp/issues) page for a solution and report the issue if it has not yet been reported.
|
||||
|
||||
And as always, feel free to hop on to our [Contributors Chat room](https://gitter.im/FreeCodeCamp/Contributors), for quick queries.
|
||||
|
||||
### Installing prerequisites
|
||||
Start by installing the prerequisite software:
|
||||
|
||||
| Prerequisite | Version | Notes |
|
||||
| --------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
Software required for both Docker and Local builds:
|
||||
|
||||
| Prerequisite | Version | Notes |
|
||||
| ------------ | ------- | ----- |
|
||||
| [Node.js](http://nodejs.org)| `10.x` | [LTS Schedule](https://github.com/nodejs/Release#release-schedule) |
|
||||
| npm (comes bundled with Node)| `6.x` | Does not have LTS releases, we use the version bundled with Node LTS |
|
||||
|
||||
**Docker Build additional prerequisite:**
|
||||
|
||||
| Prerequisite | Version | Notes |
|
||||
| ------------ | ------- | ----- |
|
||||
| [Docker CE](https://docs.docker.com/install/) | `Stable` | - |
|
||||
| [Docker Compose](https://docs.docker.com/compose/install/) | `Stable` | Must be installed separately if not using macOS or Windows |
|
||||
|
||||
**Local Build additional prerequisite:**
|
||||
|
||||
| Prerequisite | Version | Notes |
|
||||
| ------------ | ------- | ----- |
|
||||
| [MongoDB Community Server](https://docs.mongodb.com/manual/administration/install-community/) | `3.6` | [Release Notes](https://docs.mongodb.com/manual/release-notes/), Note: We are currently on `3.6`, an [upgrade is planned](https://github.com/freeCodeCamp/freeCodeCamp/issues/18275). |
|
||||
| [Node.js](http://nodejs.org) | `10.x` | [LTS Schedule](https://github.com/nodejs/Release#release-schedule) |
|
||||
| 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 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:
|
||||
We highly recommend updating to the latest stable releases of the software listed above, also known as Long Term Support (LTS) releases.
|
||||
If Node.js is already installed on your machine, run the following commands to validate the versions:
|
||||
|
||||
```sh
|
||||
node -v
|
||||
mongo --version
|
||||
npm -v
|
||||
```
|
||||
|
||||
> If you have a different version, please install the recommended version. We can only support installation issues for recommended versions.
|
||||
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 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`.
|
||||
Windows users:
|
||||
> Make sure the command line tool you use (e.g., cmd, PowerShell, Git Bash for Windows, WSL) 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 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.
|
||||
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 research your specific issue on resources such as Google, Stack Overflow and Stack Exchange. There is a good chance 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 the [contributors community on our public forum](https://www.freeCodeCamp.org/forum/c/contributors) or the [contributor's chat room](https://gitter.im/freeCodeCamp/Contributors).
|
||||
|
||||
Please avoid creating GitHub issues for prerequisite 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.**
|
||||
|
||||
### Configuring dependencies
|
||||
|
||||
@ -154,17 +175,42 @@ copy sample.env .env
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
Keep in mind if you want to use additional services, you'll have to acquire your own API keys for those services and edit the entries accordingly in the `.env` file.
|
||||
|
||||
**Docker Build:** If using the Docker build and the Docker installation instructed you to use Docker Toolbox (applies to older versions of macOS and Windows), you need to change `DOCKER_HOST_LOCATION` in your `.env` file var to the output from the `docker-machine ip` command. If you use any Docker supported flavor of Linux or if you use Docker Desktop (new versions of macOS and Windows 10) you can leave `DOCKER_HOST_LOCATION` to the default value.
|
||||
|
||||
#### Step 2: Install dependencies
|
||||
|
||||
This step will install the dependencies required for the application to run:
|
||||
|
||||
**Docker Build:**
|
||||
```shell
|
||||
npm run docker:init
|
||||
npm run docker:install
|
||||
npm run docker:seed
|
||||
```
|
||||
|
||||
Each of the Docker commands above will take some time to complete. You should wait for each command to fully complete before running the next.
|
||||
|
||||
You will also need to install a few npm packages outside of Docker. You can skip this step if you are only running the app locally and will not use git.
|
||||
|
||||
```shell
|
||||
npm ci --ignore-scripts
|
||||
```
|
||||
|
||||
All of the above needs to be run only the first time you set up the local dev environment.
|
||||
|
||||
**Local Build:**
|
||||
|
||||
```sh
|
||||
# Install NPM dependencies
|
||||
npm ci
|
||||
```
|
||||
|
||||
#### Step 3: Start MongoDB
|
||||
#### Step 3: Start MongoDB and seed the database (Local build only)
|
||||
|
||||
This step applies to the Local build only; if you are using the Docker build please skip to Step 4.
|
||||
|
||||
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:
|
||||
@ -188,16 +234,21 @@ Start the MongoDB server in a separate terminal:
|
||||
> 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/)
|
||||
|
||||
#### 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.
|
||||
|
||||
```sh
|
||||
npm run seed
|
||||
```
|
||||
|
||||
#### Step 5: Start the freeCodeCamp client application and API server
|
||||
#### Step 4: Start the freeCodeCamp client application and API server
|
||||
You can now start up the API server and the client applications.
|
||||
|
||||
**Docker Build:**
|
||||
```shell
|
||||
npm run docker:develop
|
||||
```
|
||||
|
||||
**Local Build:**
|
||||
```sh
|
||||
npm run develop
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user