Дотримуйтесь цих рекомендацій, щоб налаштувати середовище розробки freeCodeCamp. Особливо рекомендовано, якщо ви хочете робити внески регулярно.

## Оберіть між Gitpod чи власною машиною (локальне налаштування)

> [!ATTENTION] **Примітка:** freeCodeCamp НЕ працює належним чином на Windows 10 чи 11, вам потрібно використовувати WSL2. Використовуйте [цей посібник](how-to-setup-wsl.md), щоб налаштувати WSL2. Ви не можете використовувати командний рядок, Git Bash або PowerShell для запуску freeCodeCamp на Windows.

Якщо ви бажаєте зробити одноразовий внесок, використовуйте Gitpod. Налаштування Gitpod надає готове середовище у вашому браузері за декілька хвилин. Для тривалих внесків ми рекомендуємо налаштувати freeCodeCamp на локальній машині.

Ось деякі плюси та мінуси, які допоможуть із вибором:

| Gitpod                                                                    | Власна машина (локальне налаштування)                           |
| ------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Відсутність мінімальних вимог обладнання                                  | Специфічні та мінімальні вимоги                                 |
| Не потрібно встановлювати програмне забезпечення                          | Потрібно додаткове програмне забезпечення                       |
| Копія репозиторію завжди актуальна                                        | Потрібно підтримувати локальну копію репозиторію                |
| Повільніший та може займати декілька хвилин для запуску                   | Швидший та займає декілька секунд для запуску                   |
| Потрібне інтернет-з’єднання                                               | Мінімальне інтернет-з’єднання (після налаштування)              |
| Деякі завдання (наприклад, компіляція та тестування) можуть тривати довше | Швидше виконання завдань (залежно від можливостей вашої машини) |

### Як підготувати робоче середовище Gitpod

Ми автоматизували процес встановлення усіх необхідних залежностей та інструментів. Завдяки Gitpod ви отримаєте готове середовище за декілька хвилин, яке буде корисним, якщо ви не маєте доступу до комп’ютера чи хочете зробити одноразові зміни.

Існує декілька способів запустити робоче середовище Gitpod:

1. **(Найшвидший спосіб)** Додайте `gitpod.io/#` на початку будь-якого URL з GitHub.

   Наприклад, якщо ви відвідуєте розгалуження на `https://github.com/YOUR_USER_NAME/freeCodeCamp.git`, додайте `gitpod.io/#` на початку URL-адреси та натисніть клавішу enter.

   Ви перейдете на `gitpod.io/#https://github.com/YOUR_USER_NAME/freeCodeCamp.git` та побачите робоче середовище, створене для вас. Це працює для будь-якого репозиторію чи PR на GitHub.

2. В іншому випадку встановіть одне з нижчеподаних розширень браузера.

   - [Chrome Webstore](https://chrome.google.com/webstore/detail/gitpod-always-ready-to-co/dodmmooeoklaejobgleioelladacbeki) — працює з браузерами на основі Chromium (Google Chrome, Brave, Edge тощо)
   - [Firefox Add-on](https://addons.mozilla.org/en-US/firefox/addon/gitpod) — Firefox

   Як тільки розширення встановлено, ви побачите кнопку «Gitpod» на кожному репозиторії, PR тощо, що дозволить запустити робоче середовище. Перегляньте сторінку розширень для детальнішої інформації, знімків екрану тощо.

Ви можете пропустити розділ «Налаштуйте синхронізацію з батьківського елемента», як тільки запустите робоче середовище Gitpod. Більша частина цього посібника стосується робочих середовищ Gitpod, однак потрібно пам’ятати [як працюють URL-адреси та порти в межах робочого середовища Gitpod](https://www.gitpod.io/docs/configure/workspaces/ports).

**Примітка: розв’язок проблем з портом на Gitpod**

Служба на порті `8000` іноді не працює. Це типово, якщо ви перезапускаєте неактивне робоче середовище.

Якщо служба не з’являється на порті `8000`, розв’яжіть проблему за допомогою наступних кроків:

- **Запустіть сервер**: виконайте `pnpm run develop:server` у вікні терміналу з кореневого каталогу проєкту (`/workspace/freeCodeCamp`), щоб запустити сервер.

- **Запустіть клієнта**: в іншому вікні терміналу виконайте `pnpm run develop -- -H '0.0.0.0'` з каталогу клієнта (`/workspace/freeCodeCamp/client`), щоб запустити клієнта.

Це має зробити порт `8000` доступним.

### Як підготувати локальну машину

Мінімальні вимоги для локального запуску freeCodeCamp:

- 8 ГБ оперативної пам’яті
- Відносно швидкий процесор (4+ ядер)
- Windows 10 чи 11 (з WSL), macOS або Linux

Для початку встановіть передумовне програмне забезпечення для своєї операційної системи.

Здебільшого ми підтримуємо розробку на системах, які базуються на Linux та Unix (наприклад, Ubuntu та macOS). На Windows 10 чи 11 можна працювати лише з WSL2. Використовуйте [цей посібник](how-to-setup-wsl.md), щоб налаштувати WSL2. Ви не можете використовувати командний рядок, Git Bash або PowerShell для запуску freeCodeCamp на Windows.


#### Передумови:

| Передумова                                                                                    | Версія  | Примітки                                                                                          |
| --------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| [Node.js](http://nodejs.org)                                                                  | `18.x`  | Ми використовуємо версію «Active LTS», див. [розклад LTS](https://nodejs.org/en/about/releases/). |
| [pnpm](https://pnpm.io/installation)                                                          | `8.x`   | -                                                                                                 |
| [Сервер спільноти MongoDB](https://docs.mongodb.com/manual/administration/install-community/) | `5.0.x` | -                                                                                                 |

> [!ATTENTION] Якщо у вас інша версія, встановіть рекомендовану версію. Ми можемо вирішити проблеми зі встановленням лише для рекомендованих версій. Для детальнішої інформації див. [розділ з розв’язання проблем розробки](troubleshooting-development-issues.md).

Якщо на вашій машині вже встановлено Node.js, запустіть наступні команди для перевірки версій:

```console
node -v
pnpm -v
```

> [!TIP] Ми наполегливо рекомендуємо оновити вищевказані програмні забезпечення до останнього стабільного випуску, також відомого як довгострокова підтримка (LTS).

Як тільки ви встановили передумови, потрібно підготувати середовище розробки. Це характерно для багатьох робочих процесів розробки, і це потрібно зробити лише один раз.

##### Виконайте наступні дії, щоб підготувати середовище розробки:

1. Встановіть [Git](https://git-scm.com/) або інший клієнт Git, якщо ви досі цього не зробили. Оновіть його до останньої версії; версія, яка пов’язана з вашою ОС, може бути застарілою.

2. (Необов’язково, але рекомендовано) [Налаштуйте ключ SSH](https://help.github.com/articles/generating-an-ssh-key/) для GitHub.


3. Встановіть редактор коду на свій вибір. Якщо ви вагаєтесь, ми рекомендуємо [Visual Studio Code](https://code.visualstudio.com/) — він безоплатний та має відкритий код.

4. Налаштуйте лінтинг для редактора коду.

   Ви повинні [запустити ESLint у своєму редакторі](http://eslint.org/docs/user-guide/integrations.html), оскільки він виділятиме все, що не відповідає [нашій інструкції з оформлення JavaScript](http://forum.freecodecamp.org/t/free-code-camp-javascript-style-guide/19121).

   > [!TIP] Будь ласка, не ігноруйте помилки лінтингу. Вони **допомагають** забезпечувати чисту й просту базу коду.

## Розгалужте репозиторій на GitHub

[Розгалуження](https://help.github.com/articles/about-forks/) — це етап, на якому ви отримаєте власну копію головного репозиторію freeCodeCamp на GitHub.

Це дуже важливо, оскільки ви зможете працювати над власною копією freeCodeCamp на GitHub або завантажити (клонувати) репозиторій для локальної роботи. Пізніше ви зможете запропонувати внести зміни до головного репозиторію зі свого розгалуження за допомогою запиту на злиття (PR).

> [!TIP] Головний репозиторій на `https://github.com/freeCodeCamp/freeCodeCamp` часто називають репозиторієм `upstream`.
> 
> Ваше розгалуження на `https://github.com/YOUR_USER_NAME/freeCodeCamp` часто називають репозиторієм `origin`. `YOUR_USER_NAME` буде змінено на ваше ім’я користувача GitHub.

**Виконайте наступні кроки, щоб розгалужити репозиторій `https://github.com/freeCodeCamp/freeCodeCamp`:**

1. Перейдіть до репозиторію freeCodeCamp на GitHub: <https://github.com/freeCodeCamp/freeCodeCamp>

2. Натисніть кнопку «Fork» у верхньому правому куті інтерфейсу ([детальніша інформація тут](https://help.github.com/articles/fork-a-repo/))

3. Як тільки репозиторій розгалужено, вас буде переміщено до копії репозиторію freeCodeCamp на `https://github.com/YOUR_USER_NAME/freeCodeCamp` (`YOUR_USER_NAME` буде змінено на ваше ім’я користувача GitHub.)

<details>
   <summary>
      Як розгалужити freeCodeCamp на GitHub (знімок екрана)
   </summary>

   <br>
   <img src="https://raw.githubusercontent.com/freeCodeCamp/freeCodeCamp/main/docs/images/github/how-to-fork-freeCodeCamp.gif" alt="Як розгалужити freeCodeCamp на GitHub" />
</details>

## Клонуйте розгалуження з GitHub

[Клонування](https://help.github.com/articles/cloning-a-repository/) — це **завантаження** копії репозиторію з `віддаленого` розташування, що належить вам або комусь іншому. У цьому випадку віддаленим розташуванням є ваш `fork` репозиторію freeCodeCamp, який доступний на `https://github.com/YOUR_USER_NAME/freeCodeCamp`. (`YOUR_USER_NAME` буде змінено на ваше ім’я користувача GitHub.)

> [!WARNING] Якщо ви використовуєте дистрибутив WSL2 Linux, у вас можуть виникнути проблеми, пов’язані з продуктивністю та стабільністю під час запуску цього проєкту в папці, спільній між Windows і WSL2 (наприклад, `/mnt/c/Users/`). Ми рекомендуємо клонувати цей репозиторій до папки, яка в основному використовується дистрибутивом WSL2 Linux і не має прямого доступу до Windows (наприклад, `~/PROJECTS/`).
> 
> Див. [завдання на GitHub](https://github.com/freeCodeCamp/freeCodeCamp/issues/40632) для детальнішої інформації щодо цієї проблеми.

Запустіть ці команди на своїй локальній машині:

1. Відкрийте термінал / командний рядок / оболонку в каталозі проєктів

   _тобто `/yourprojectsdirectory/`_

2. Клонуйте своє розгалуження freeCodeCamp, замінивши `YOUR_USER_NAME` на ім’я користувача GitHub

   ```console
   git clone --depth=1 https://github.com/YOUR_USER_NAME/freeCodeCamp.git
   ```

Це завантажить весь репозиторій freeCodeCamp у ваш каталог проєктів.

Зверніть увагу: `--depth=1` створює поверхневий клон вашого розгалуження, використовуючи лише останню історію/затвердження.

## Налаштуйте синхронізацію з батьківського репозиторію

Ви завантажили копію розгалуження, а отже вам потрібно налаштувати `upstream` віддалено від батьківського репозиторію.

[Як згадувалось раніше](#fork-the-repository-on-github), головний репозиторій має назву `upstream`. Розгалуження називають репозиторієм `origin`.

Вам потрібне посилання від локального клону на репозиторій `upstream` на додаток до репозиторію `origin`. Це необхідно для того, щоб ви могли синхронізувати зміни з головного репозиторію без багаторазового розгалуження і клонування.

1. Змініть каталог на новий каталог freeCodeCamp:

   ```console
   cd freeCodeCamp
   ```

2. Додайте віддалене посилання на основний репозиторій freeCodeCamp:

   ```console
   git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git
   ```

3. Переконайтеся, що конфігурація правильна:

   ```console
   git remote -v
   ```

   Вивід повинен бути схожим на нижчеподаний приклад (замініть `YOUR_USER_NAME` на своє ім’я користувача GitHub):

   ```console
   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)
   ```

## Локальний запуск freeCodeCamp

Тепер у вас є локальна копія freeCodeCamp, тому дотримуйтесь цих інструкцій для локального запуску. Це дозволить вам:

- Переглядати як виглядатиме навчальна платформа з внесеними змінами.
- Працювати над завданнями та покращеннями UI.
- Виправляти помилки серверів застосунків та клієнтських застосунків.

Якщо у вас виникли проблеми, спочатку спробуйте знайти розв’язок в інтернеті. Якщо розв’язку немає, пошукайте його на нашій сторінці [завдань GitHub](https://github.com/freeCodeCamp/freeCodeCamp/issues) та повідомте про проблему, якщо про неї ще не повідомляли.

І як завжди, не соромтесь ставити запитання [на форумі у категорії «Contributors»](https://forum.freecodecamp.org/c/contributors) або [у чаті](https://discord.gg/PRyKn3Vbay).

### Налаштування залежностей

#### Крок 1: налаштуйте файл змінних середовища

Ключі API та змінні середовища за замовчуванням зберігаються у файлі `sample.env`. Цей файл потрібно скопіювати в новий файл під назвою `.env`, доступ до якого відкривається динамічно на кроці встановлення.

```console
# Створіть копію «sample.env» та назвіть її «.env».
# Заповніть її необхідними ключами та секретами API:
```

<!-- tabs:start -->

#### **macOS/Linux**

```console
cp sample.env .env
```

#### **Windows**

```console
copy sample.env .env
```

<!-- tabs:end -->

Для локального запуску застосунку _необов’язково_ змінювати ключі у файлі `.env`. Ви можете залишити значення за замовчуванням, скопійовані з `sample.env`.

> [!TIP] Майте на увазі, якщо ви використовуватимете Auth0 або Algolia, вам потрібно отримати власні ключі API для цих служб та відредагувати введені дані у файлі `.env`.

#### Крок 2: встановіть залежності

У цьому кроці буде встановлено залежності, необхідні для запуску застосунку:

```console
pnpm install && pnpm run create:config
```

#### Крок 3: запустіть MongoDB та додайте базу даних

Перш ніж локально запустити застосунок, потрібно запустити службу MongoDB.

> [!NOTE] Якщо MongoDB працює за замовчуванням, то URL-адреса, збережена як значення `MONGOHQ_URL` у файлі `.env`, має працювати. Якщо ви використовуєте власне налаштування, змініть значення за потреби.
> 
> Якщо ви дотримувались [посібника з налаштування Windows 10 з WSL2](how-to-setup-wsl.md), ви можете пропустити цей крок за умови, що сервер MongoDB вже працює. Це можна перевірити, зв’язавшись із `http://localhost:27017` на локальній машині.

Запустіть сервер MongoDB в окремому терміналі:

  <!-- tabs:start -->

#### **macOS/Linux**

```console
mongod
```

#### **Windows**

- На Windows ви повинні вказати повний шлях до двійкового файлу `mongod`

```console
"C:\Program Files\MongoDB\Server\3.6\bin\mongod"
```

Не забудьте змінити `3.6` на свою версію

  <!-- tabs:end -->

> [!TIP] Ви можете не запускати MongoDB кожного разу, встановивши його як фонову службу. Для детальнішої інформації див. [документацію MongoDB для вашої ОС](https://docs.mongodb.com/manual/administration/install-community/)

Тепер додамо базу даних. На цьому кроці ми запускаємо нижченаведену команду, яка заповнює сервер MongoDB деякими початковими наборами даних, потрібних службам. До них належать деякі схеми та інше.

```console
pnpm run seed
```

#### Крок 4: запустіть клієнтську програму freeCodeCamp та сервер API

Тепер ви можете запустити сервер API та клієнтську програму.

```console
pnpm run develop
```

Ця команда запустить всі служби, включно з сервером API та клієнтською програмою, з якими ви можете працювати.

Після цього відкрийте веббраузер та відвідайте <http://localhost:8000>. Якщо застосунок завантажується, увійдіть в систему. Вітання — все готово! Тепер ви маєте копію повної навчальної платформи freeCodeCamp на своїй локальній машині.

Сервер API обслуговує кінцеві точки на `http://localhost:3000`. Gatsby обслуговує клієнтську програму на `http://localhost:8000`.

Якщо ви увійшли в систему, відвідайте <http://localhost:3000/explorer> і побачите доступні API.

> [!WARNING] Якщо очистити cookies чи запустити `pnpm run seed:certified-user`, ви вийдете з системи та вам доведеться увійти знову.

Якщо у вас виникли проблеми, див. розділ з [розв’язання проблем розробки](troubleshooting-development-issues.md).

## Коротко про команди

Короткий довідник команд, які знадобляться при локальній роботі.

| команда            | опис                                                                 |
| ------------------ | -------------------------------------------------------------------- |
| `pnpm install`     | Встановлює/перевстановлює всі залежності та запускає різні служби.   |
| `pnpm run seed`    | Створює авторизованих тестових користувачів і розміщує їх у MongoDB. |
| `pnpm run develop` | Запускає сервер API та клієнтські програми freeCodeCamp.             |
| `pnpm run clean`   | Видаляє всі залежності та очищує кеш.                                |
