--- title: "Set up a dev environment for freeCodeCamp" --- > Documentation Index > Fetch the complete documentation index at: https://contribute.freecodecamp.org/llms.txt > Use this file to discover all available pages before exploring further. # Set up a dev environment for freeCodeCamp This guide sets up a development environment for freeCodeCamp. Work through it once, in order. > **Windows users: read this first** > > This project supports macOS and Linux only. Set up [WSL2](/how-to-setup-wsl) first, then follow this guide inside it. Use [Windows Terminal](https://github.com/microsoft/terminal) — not Command Prompt, Git Bash, or PowerShell. ## Fork the freeCodeCamp repository on GitHub A [fork](https://help.github.com/articles/about-forks) is your own copy of the codebase. You need one to contribute. 1. Open the fork page: [Fork freeCodeCamp](https://github.com/freeCodeCamp/freeCodeCamp/fork) 2. Check the details, then click **Create fork**. 3. GitHub redirects you to your fork at `https://github.com/YOUR_USER_NAME/freeCodeCamp`. In this guide, `origin` means your fork and `upstream` means the main repository. You can delete your fork at any time and start again. ## Choose where to run freeCodeCamp There are three ways to run the project. All three work. Compare them, pick one, then follow that tab below. | Feature | Local Machine | Dev Container | GitHub Codespaces | | ---------------------------- | ---------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ | | **Where it runs** | Directly on your machine | In Docker, on your machine | On a GitHub server | | **You install** | Node.js, pnpm, Docker Compose, Git | Docker Desktop, VS Code, Dev Containers extension, Git | Nothing | | **You manage tool versions** | Yes | No. The image carries them | No. The image carries them | | **Machine needed** | 4 CPUs, 8 GB of RAM, 10 GB of disk | 4 CPUs and 16 GB of RAM given to Docker, plus your own operating system on top | A 4-core, 16 GB, 32 GB disk machine. The project sets this minimum | | **Speed** | Fastest | Slower file access on macOS and Windows | Depends on your connection | | **Works offline** | Yes, after setup | Yes, after the first start | No | | **Cost** | Free | Free | A free monthly quota, then paid | Each option gives you the same running application, so pick the one that fits your machine. ## Clone your fork Skip this section if you picked GitHub Codespaces — it clones your fork for you. You need [Git](https://git-scm.com/) installed first. 1. Clone your fork, replacing `YOUR_USER_NAME` with your GitHub username: ```bash git clone --depth=1 https://github.com/YOUR_USER_NAME/freeCodeCamp.git cd freeCodeCamp ``` 2. Add a remote that points at the main repository, so you can sync later: ```bash git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git ``` Run `git remote -v` to confirm. You should see `origin` on your fork and `upstream` on `freeCodeCamp/freeCodeCamp`. 3. **(Optional)** To work on a localized curriculum, fetch the [i18n-curriculum](https://github.com/freeCodeCamp/i18n-curriculum) submodule: ```bash git submodule update --init ``` ## Set up and run freeCodeCamp ### Local Machine ### Local machine prerequisites Your machine needs 4 CPU cores, 8 GB of RAM and 10 GB of free disk space, on macOS or Linux. | Prerequisite | Version | Notes | | - | - | - | | [Git](https://git-scm.com/) | latest | The version bundled with your operating system is often outdated. | | [Node.js](http://nodejs.org) | `24.x` | The "Active LTS" version. See the [LTS schedule](https://nodejs.org/en/about/releases/). | | [pnpm](https://pnpm.io/installation) | `12.x` | - | | [Docker Compose](https://docs.docker.com/compose/install/) | `2.x` | Starts MongoDB for you below. | | [MongoDB Community Server](https://docs.mongodb.com/manual/administration/install-community/) | `8.x` | Optional. Only if you prefer to run MongoDB without Docker. | Check what you have: ```bash node -v && pnpm -v ``` > **Versions matter** > > A version other than the one listed is the most common cause of a failed setup. See [troubleshooting](/troubleshooting-development-issues/). Recommended, but not required: - [Set up an SSH key](https://help.github.com/articles/generating-an-ssh-key/) for GitHub. - Use a code editor. [Visual Studio Code](https://code.visualstudio.com/) is free and open source. - Run [ESLint in your editor](http://eslint.org/docs/user-guide/integrations.html). It flags anything that breaks freeCodeCamp's [JavaScript Style Guide](http://forum.freecodecamp.org/t/free-code-camp-javascript-style-guide/19121). ### Start the app 1. Create your environment file: ```bash cp sample.env .env ``` The defaults run the app as it is. Change them only if you want your own Auth0, Algolia or Stripe keys. 2. Install dependencies: ```bash pnpm install ``` WSL users: run `pnpm run playwright:install-build-tools` first. It installs system packages that Playwright and Puppeteer need. 3. Stop any MongoDB server already using port 27017, then start MongoDB as a replica set: ```bash docker compose -f docker/docker-compose.yml -f docker/docker-compose.ports.yml up -d ``` This also starts Mailpit, which catches outgoing email at `http://localhost:8025`. 4. Seed the database: ```bash pnpm run seed ``` This creates a test user with no completed certifications. For a user with certifications, run `pnpm run seed:certified-user` instead, then clear your browser cookies and sign in again. 5. Start the client and the API: ```bash pnpm run develop ``` A full curriculum build takes several minutes. Open `http://localhost:8000` when it finishes. > **Using your own MongoDB** > > If you run MongoDB outside Docker, point `MONGOHQ_URL` in `.env` at it. It must be a replica set. ### Dev Container A dev container runs the same image as GitHub Codespaces, on your own machine. The image includes Node.js, pnpm and dependency caches. Container setup installs the project dependencies and starts MongoDB and Mailpit as separate services. ### Dev container prerequisites | Prerequisite | Notes | | - | - | | [Git](https://git-scm.com/) | - | | [Docker Desktop](https://docs.docker.com/get-started/get-docker/) | Any Docker Engine with Compose v2 works. | | [Visual Studio Code](https://code.visualstudio.com/) | - | | [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) | - | In Docker's resource settings, give it at least 4 CPUs and 16 GB of memory. The client build needs a 7 GB heap, and Docker treats its memory setting as a hard limit. ### Open and run the project 1. Open the folder in VS Code: ```bash code . ``` 2. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`), then select **Dev Containers: Reopen in Container**. 3. Wait for the setup to finish. The terminal shows `Done. Press any key to close the terminal.` The container installs the dependencies, writes `.env`, starts MongoDB and Mailpit, and seeds the database for you. 4. Open the Command Palette again, type `Run Task`, then select **Start freeCodeCamp**. Or open a terminal and run: ```bash pnpm run develop ``` 5. Wait for the build. It takes several minutes the first time. Then open `http://localhost:8000`. > **The first start is slow** > > The first start downloads a prebuilt image of several gigabytes. Later starts are fast. ### GitHub Codespaces A codespace runs the project on a GitHub server. You install nothing, and you work in your browser or in VS Code. 1. Go to your fork at `https://github.com/YOUR_USER_NAME/freeCodeCamp`. 2. Click the green **Code** button, select the **Codespaces** tab, then click **Create codespace on main**. Pick the **4-core, 16 GB RAM** machine, or a larger one. The codespace then installs every dependency, starts MongoDB and Mailpit, seeds a test user, writes `.env`, and installs the ESLint and Prettier extensions. 3. Wait for the setup to finish, then open a terminal and run: ```bash pnpm run develop ``` 4. Wait for the build. It takes several minutes the first time. VS Code shows a notification for port `8000` when the client is ready — open it to view the client in a new browser tab. > **Keep port 3000 public** > > The client calls the API across two forwarded origins, so port `3000` must stay public or the browser reports a CORS error. The container sets this on every start, but if it still looks private, open the **Ports** panel, right-click port `3000`, then choose **Port Visibility > Public**. Leave port `8000` private. > > A public port is reachable by anybody who has the URL. Stop the codespace when you finish working. ## After it starts - The API serves endpoints at `http://localhost:3000`, with docs at `/documentation`. In Codespaces, open these from the **Ports** panel. - Mailpit catches outgoing email at `http://localhost:8025` (or the **Ports** panel in Codespaces). **Working on curriculum content?** Build only the part you need. It is far faster: ```bash FCC_SUPERBLOCK='responsive-web-design-v9' pnpm run develop ``` See [Quick Commands Reference](#quick-commands-reference) for `FCC_BLOCK` and `FCC_CHALLENGE_ID`. > **Congratulations — you're all set!** > > freeCodeCamp's learning platform is now running. If anything failed, see [troubleshooting](/troubleshooting-development-issues/). ## Quick Commands Reference | Command | Description | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | `pnpm install` | Installs / re-installs all dependencies. | | `pnpm run seed` | Creates authorized test users and inserts them into MongoDB. Also runs `seed:exams` and `seed:surveys` below. | | `pnpm run seed:certified-user` | Creates authorized test users with certifications fully completed, and inserts them into MongoDB. | | `pnpm run seed:exams` | Creates exams and inserts them into MongoDB. | | `pnpm run seed:surveys` | Creates surveys for default users and inserts them into MongoDB. | | `FCC_SUPERBLOCK='responsive-web-design-v9' pnpm run develop` | Starts the API Server and Client, building only the specified SuperBlock (recommended for curriculum work). | | `FCC_BLOCK='workshop-curriculum-outline' pnpm run develop` | Starts the API Server and Client, building only the specified Block (recommended for curriculum work). | | `FCC_CHALLENGE_ID=646cf6cbca98e258da65c979 pnpm run develop` | Starts the API Server and Client, building only the specified Challenge (recommended for curriculum work). | | `pnpm run develop` | Starts the freeCodeCamp API Server and Client Applications with full curriculum build (for thorough testing). | | `pnpm run clean` | Uninstalls all dependencies and cleans up caches. | Source: https://contribute.freecodecamp.org/how-to-setup-freecodecamp-locally/index.mdx