Инструкция по развертыванию CRYSTAL v1.0 на локальном ПК

Структура проекта:

• MongoDB v8.0.4.
• Express.js v4.21.2.
• React v19.0.0.
• Node.js v24.0.2.
• NPM v11.3.0.
• Vite v6.1.0.

Характеристики локального ПК:

• OS: Windows 11 Pro, далее - Win 11.
• Командная строка (Windows терминал), далее - терминал.
• MongoDB Compass v1.45.0.
• MongoDB Community Server v8.0.4.

Необходимо, последовательно выполнять все пункты.

1. Установка Node.js, npm и Git.

1.1. Установка Node.js и npm.

Скачайте и установите Node.js. Во время установки, принимайте значения по умолчанию. Совместно с Node.js, автоматически установитcя npm.

Далее, нажмите на клавиатуре - 'Win+R', затем введите в открывшимся окне:

cmd

Далее нажмите - 'Enter', откроется терминал, введите в нем, команду ниже, которая покажет версии Node.js и npm:

node -v && npm -v

1.2. Установка Git.

Скачайте и установите Git. Во время установки, принимайте значения по умолчанию.

Проверьте версию Git, после установки:

git -v

2. Создание директории с проектом на локальном ПК.

Проект будет клонирован с помощью GitHub CLI, но вы можете использовать другие методы (HTTPS, SSH). Подробнее о GitHub CLI, установщик.

Работа с файлами в данной инструкции, будет происходить на диске - 'C'.

Введите в терминале, команду ниже:

mkdir C:\GitProjects && cd C:\GitProjects && gh repo clone CrystalSystems/crystal-v1.0

Данная команда, создаст папку 'GitProjects' по адресу - 'C:\GitProjects', и клонирует в неё - CRYSTAL v1.0, из репозитория проекта.

3. Установка базы данных MongoDB.

3.1. Установка MongoDB Community Server.

Скачайте и установите MongoDB Community Server (если у вас не открывается ссылка, используйте VPN), в поле - 'Platform', выберите - 'Windows x64', в поле - 'Package', выберите - 'msi. В установщике, выберите - 'Complete' и нажмите - 'Next', завершите установку, принимая значения по умолчанию. MongoDB установится по адресу - "C:\Program Files\MongoDB", дополнительно должна установиться программа - MongoDB Compass.

3.2. Запуск сервера MongoDB.

Если ваша версия MongoDB, будет выше 8, измените номер версии в команде ниже. Уточните номер версии по адресу - 'C:\Program Files\MongoDB\Server'.

Введите в терминал команду:

cd C:\Program Files\MongoDB\Server\8.0\bin\ && mongod.exe

4. Запуск frontend части проекта и создание файла .env.

4.1. Создание файла .env.dev с адресом локального сервера.

Введите в терминал команду:

mkdir C:\GitProjects\crystal-v1.0\frontend\env && cd C:\GitProjects\crystal-v1.0\frontend\env && echo VITE_BASE_URL=http://localhost:3000 > .env.dev

4.2. Установка зависимостей.

Введите команду:

cd C:\GitProjects\crystal-v1.0\frontend && npm i

4.3. Запуск frontend части проекта.

Введите команду:

npm run dev

После успешного запуска, frontend часть проекта, будет доступна по адресу:

http://localhost:8200/

5. Запуск backend части проекта и создание файлов .env.

Откройте дополнительное окно терминала.

5.1. Создание файла .env с секретным ключем JSON Web Token и Email администратора.

Введите команду, для создания папки - 'env':

mkdir C:\GitProjects\crystal-v1.0\backend\env && cd C:\GitProjects\crystal-v1.0\backend\env

Далее, необходимо задать значение переменной - 'JWT_SECRET_KEY'.

Для генерации значения переменной - 'JWT_SECRET_KEY', нажмите клавишу - 'F12' в браузере Chrome (подойдет любой современный браузер) и введите в консоль, следующий код:

function generateJWTSecretKey(length = 80) {

const charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*()_+-=[]{}|:,.<>?";
  const array = new Uint8Array(length);
  window.crypto.getRandomValues(array);
  return Array.from(array)
    .map(b => charset[b % charset.length])
    .join('');
}

const jwtSecretKey = generateJWTSecretKey();

console.log(`JWT_SECRET_KEY="${jwtSecretKey}"`);

* Энтропия ключа, созданного данным способом, составляет примерно от 450 до 515 бит.

После ввода, вы получите криптографически стойкий - 'JWT_SECRET_KEY'.

Пример вывода в консоли браузера:

JWT_SECRET_KEY="IW4%ur)Zn5XWqbO[xTYwO&8qi!6<uoi1WZpFTSONl=!cBs5{lA)fV,cgIn}@EP0YSTvnOTsAeIq1A)|X"

Далее, введите в терминал команду с вашим - 'JWT_SECRET_KEY':

echo JWT_SECRET_KEY="Секретный_ключ_JWT" > .env

При регистрации пользователя с email, таким же, как в переменной - 'CREATOR_EMAIL', будет включен режим администратора (редактирование/удаление пользователей и постов). Измените данные в команде ниже, на нужный email.

echo CREATOR_EMAIL=email_для_режима_администратора >> .env

5.2. Создание файла .env.dev

Переменная - 'PRODUCTION_STATUS', в файле .env.dev, определяет в каком режиме будет запускаться сервер, в данном случае - режим разработки.

Введите команду:

echo PRODUCTION_STATUS=false > .env.dev

5.3. Установка зависимостей.

Введите команду:

cd C:\GitProjects\crystal-v1.0\backend & npm i

5.4. Запуск backend часть проекта.

Введите команду:

npm run startDev

После успешного запуска, в терминале должны появиться сообщения - 'Server is running' и 'DB connected'.

Перейдите в окно браузера с проектом, по адресу - http://localhost:8200/, обновите страницу, затем зарегистрируйтесь и добавьте пост.

6. MongoDB Compass.

Откройте MongoDB Compass, и нажмите на кнопку - 'Add new connection', в поле - 'URI', должен быть адрес - 'mongodb://localhost:27017', нажмите кнопку - 'Save & Connect', после этого в списке бд слева, должна появиться база данных под названием - 'crystal', в которой будут две коллекции - 'posts' и 'users'.

Код ниже, находится в директории - 'backend\server.js' и отвечает за подключение к локальному серверу MongoDB, а также за то, что база данных будет называться - 'crystal'.

mongoose.connect(
    "mongodb://127.0.0.1:27017/crystal"
  )

Возможные проблемы.

Ошибка - 'MongoError: connect ECONNREFUSED 127.0.0.1:27017' (не запускается БД).

Это может произойти из-за того, что служба MongoDB не запущена, чтобы запустить ее, выполните следующие шаги:

нажмите 'Win + R', в открывшимся окне ведите - 'Services.msc' и нажмите - 'Enter'.

В открывшимся окне - 'Службы', найдите - 'MongoDB Server (MongoDB)', щелкните правой кнопкой мыши и выберите - 'Запустить'. MongoDB Server запустится, выполните команду - 'npm run startDev' еще раз.