Инструкция по развёртыванию CRYSTAL v1.0 на VPC и настройка доступа к сайту по публичному IP

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

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

Характеристики виртуальной машины, далее - ВМ:

• Гарантированная доля vCPU: 30%.
• vCPU: 2.
• RAM: 4 ГБ.
• SSD: 20 ГБ.
• OS: Debian 12.
• Web server: Nginx v1.22.1.

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

• OS: Windows 11 Pro, далее - Win 11.
• Командная строка (Windows терминал), далее - терминал.

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

1. Создание репозитория с проектом CRYSTAL v1.0.

Вы можете сделать репозиторий с проектом на GitHub скрытым и после изменения файлов проекта на локальном ПК, проект можно будет обновить на ВМ, с помощью команды - 'git pull', о том, как это сделать, будет рассмотрено в 16 пункте, также для работы со скрытым репозиторием, необходимо сделать аутентификацию на GitHub через ВМ, это будет произведено в 9 пункте.

Далее, создайте в вашем GitHub аккаунте скрытый (данная инструкция рассчитана на то, что репозиторий будет скрытым) или открытый репозиторий проекта, под названием - 'crystal'. Вы можете сделать 'fork' (репозиторий fork, нельзя скрыть) или импортировать проект из репозитория CRYSTAL v1.0.

2. Создание ключа SSH.

Ключ SSH, нужен для подключения к ВМ с другого ПК, в данном случае через терминал в Win 11. Win 11 поставляется со встроенным клиентом OpenSSH, который можно использовать для генерации ключей SSH.

Чтобы создать SSH ключ, нажмите на клавиатуре - 'Win+R', затем введите в открывшимся окне - 'cmd' и нажмите - 'Enter', откроется терминал, введите в нём команду:

ssh-keygen -t ed25519

Далее введите название ключа:

crystal_key

После ввода ключа, нажмите - 'Enter'.

Вам будет предложено создать пароль, это не является обязательным, но повысит безопасность, так как, при каждом подключении к ВМ, нужно будет вводить пароль. Местоположение ключа по умолчанию - 'C:\Users\ИмяПользователя\'. После создания ключа, появятся два файла, один с расширением .pub (открытый ключ) и без расширения (закрытый ключ), переместите файлы по адресу - 'C:\Users\ИмяПользователя\.ssh\'. В дальнейшем, открытый ключ будет добавлен в ВМ на облачном сервисе. С помощью закрытого ключа, будет происходить подключение к ВМ, через терминал в Win 11.

В данной инструкции, для создания ВМ используется облачный сервис - Cloud.ru, но, так как, у всех сервисов, одинаковый принцип работы, вы можете использовать другой.

Далее, перейдите на главную страницу сервиса.

3. Создание группы безопасности в VPC.

Выберите платформу - Evolution.

Далее, откройте меню слева, и перейдите в раздел - 'Группы безопасности', затем выберите - 'Создать группу безопасности'.

Заполните пункты, как в примере ниже:

Зона доступности - ru.AZ-1 (может быть любая, но у группы безопасности и ВМ, должна быть одинаковая зона доступности).

Название - crystal.

Описание - можно не заполнять.

Теги - можно не заполнять.

Далее нужно открыть порты 80, 443 и 22, для доступа к сайту и ВМ из интернета.

Описание портов:

443 - доступ по HTTPS.

80 - доступ по HTTP.

22 - для доступа к ВМ, через ключ SSH, созданный ранее.

В пункте - 'Правила входящего трафика', нажмите - 'Добавить правило' и заполните пункты, как в примере на скриншоте № 2.

Скопируйте IP ниже, и введите его в поле 'Источник':

0.0.0.0/0

В поле 'Описание', введите:

HTTPS IPv4

После заполнения, нажмите кнопку - 'Создать'.

Далее, добавьте остальные правила входящего трафика. В итоге должно получиться, как на скриншоте № 3.

Добавьте правила исходящего трафика, как на скриншоте № 4.

Скопируйте, для заполнения поля 'Описание':

All egress IPv4

После добавления правила исходящего трафика, нажмите на кнопку - 'Создать' (группу безопасности).

4. Создание ВМ.

Откройте в меню, раздел - 'Виртуальные машины', и выберите - 'Создать виртуальную машину'.

Заполните пункты, как в примере ниже.

Конфигурация

Название - crystal.

Описание - можно не заполнять.

Теги - можно не заполнять.

Зона доступности - ru.AZ-1 (должна быть, как в ранее созданной группе безопасности).

Не создавайте группу размещения.

Образ:

Публичные - Debian 12.

Вычислительный ресурс:

Гарантированная доля vCPU - 30%

vCPU - 2

RAM - 4

Диски:

Загрузочный диск

Название - по умолчанию

Тип - SSD

Размер - 20ГБ

Настройки

Сетевые настройки

Не подключать к подсети.

Должно быть отмечено - 'Подключить публичный IP' (К ВМ подключится, автоматически созданный, статический публичный IP-адрес).

Тип IP - Прямой.

Группы безопасности - выберите ранее созданную группу безопасности - 'crystal'.

Дополнительные параметры системы

Имя хоста - crystal.

Авторизация пользователя

Логин - crystal-vm.

Метод аутентификации

Выберите - 'Публичный ключ'.

Так же, вы можете задать пароль для подключения к ВМ, через виртуальную консоль - Cloud.ru. Подключение будет доступно только внутри сервиса Cloud.ru, а не через интернет, так как, по умолчанию - 'PasswordAuthentication no'.

Далее нажмите - 'Добавить новый ключ', выберите - 'Загрузить из файла', затем перейдите в директорию - 'C:\Users\ИмяПользователя\.ssh\' и выберите ранее созданный публичный ключ - 'crystal_key.pub'.

После добавления файла ключа, введите в поле - 'Название', имя ключа - crystal_key.pub, после, нажмите кнопку - 'Добавить'.

Далее, нажмите на кнопку - 'Создать' (ВМ).

В случае успеха, ВМ должна быть создана и через некоторое время, будет доступна.

5. Подключение к ВМ, через терминал в Win 11.

Вы можете найти публичный IP адрес вашей ВМ, в разделе - 'Виртуальные машины', в одноимённой колонке.

Измените примерный текст, и введите в терминал команду:

ssh -i C:\Users\ИмяПользователя\.ssh\crystal_key crystal-vm@ПубличныйIPАдресВМ

Пример команды:

ssh -i C:\Users\Andrew\.ssh\crystal_key crystal-vm@55.55.55.55

После ввода команды, нажмите - 'Enter'. Если будет вопрос - 'Are you sure you want to continue connecting (yes/no/[fingerprint])?' введите - ' yes', далее введите пароль, который устанавливали при создании SSH-ключа.

6. Установка Node.js, npm и npx.

В дальнейшем, при вводе команд, может появиться вопрос - 'Do you want to continue? [Y/n]', в таком случае, введите - 'Y', и далее нажмите - 'Enter'.

6.1. Включите sudo, командой:

sudo -i

6.2. Обновите информацию о пакетах и обновите пакеты, командой:

apt update && apt -y upgrade

Если при установке откроется окно с вопросами, нажмите клавишу - 'Enter'.

6.3. Установите Node.js, npm и npx, последовательно выполняя команды ниже:

apt install curl -y

cd /usr/local/src
curl -O https://nodejs.org/dist/v24.0.2/node-v24.0.2-linux-x64.tar.xz

tar -xf node-v24.0.2-linux-x64.tar.xz

mv node-v24.0.2-linux-x64 /usr/local/node-v24.0.2

ln -sf /usr/local/node-v24.0.2/bin/node /usr/bin/node && ln -sf /usr/local/node-v24.0.2/bin/npm /usr/bin/npm && ln -sf /usr/local/node-v24.0.2/bin/npx /usr/bin/npx

node -v && npm -v && npx -v

echo 'export PATH=/usr/local/node-v24.0.2/bin:$PATH' >> ~/.bashrc

source ~/.bashrc

7. Установка Nginx.

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

apt-get install nginx && nginx -v

В случае успешной установки, в консоли должна быть показана версия nginx, например - 'nginx version: nginx/1.22.1'.

8. Установка git и GitHub.

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

apt install git && apt install gh

9. Аутентификация на GitHub через ВМ.

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

gh auth login

Из предложенных вариантов выберите - 'GitHub.com', далее - 'HTTPS', далее - 'Authenticate Git with your GitHub credentials?' - 'Y', затем 'Login with a web browser', после, нажмите - Enter, будет ошибка, так как, работа ведётся из консоли.

Далее, скопируйте ссылку и откройте её в браузере, из которого уже был осуществлен вход в ваш акаунт GitHub:

https://github.com/login/device

После, введите в открывшимся окне, код из терминала, как на скриншоте № 5.

Нажмите - 'Authorize github'. Если всё пройдет удачно, в конце вы увидите сообщение, как на скриншоте № 6.

Через некоторое время, в консоли должно появится подобное сообщение - '✓ Authentication complete.'.

10. Клонирование репозитория с проектом из GitHub в ВМ.

Введите команду, и замените в ней примерный текст, на ваш логин в GitHub:

cd /var/www/ && gh repo clone ВашЛогинGitHub/crystal

11. Настройка 'sites-available' и 'sites-enabled' в Nginx.

11.1. В папке 'sites-available' по адресу - '/etc/nginx/sites-available', будут дефолтные настройки сервера Nginx, нужно удалить эти настройки и заменить их своими.

В данной инструкции, будет использоваться текстовый редактор nano. В Debian 12 на ВМ, nano установлен по умолчанию, проверьте установлен ли этот редактор у вас в системе, введя команду:

nano --version

Должно появиться, подобное сообщение - 'GNU nano, version 7.2', если его нет, установите nano командами, которые подходят для вашей системы или используйте другой редактор. Вы можете включить в редакторе, управление мышью, для этого нажмите - 'alt + m' (должна быть включена английская раскладка клавиатуры).

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

rm /etc/nginx/sites-available/default && nano /etc/nginx/sites-available/crystal

Добавьте в открывшиеся окно, код ниже. Замените пример текста в строке 4, на публичный IP адрес вашей ВМ:

server {
	listen 80;
	listen [::]:80;
	server_name 'добавьте здесь публичный IP адрес вашей ВМ, без апострофов';
	location /
	{
		root /var/www/crystal/frontend/dist;
		try_files $uri $uri /index.html;
	}
	location /api/
	{
		proxy_pass http://localhost:3000/;
		proxy_hide_header X-Powered-By;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection 'upgrade';
		proxy_set_header Host $host;
		proxy_cache_bypass $http_upgrade;
	}
}

После добавления кода, нажмите последовательно - 'ctrl + x', 'y', 'Enter'.

11.2. Создание символической ссылки для сайта (sites-enabled).

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

rm /etc/nginx/sites-enabled/default && ln -s /etc/nginx/sites-available/crystal /etc/nginx/sites-enabled/ && systemctl restart nginx

12. Установка frontend части проекта и создание файла .env.prodIP.

12.1. Создание файла .env.prodIP.

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

cd /var/www/crystal/frontend && mkdir env

В следующей команде, добавьте публичный IP адрес ВМ:

echo VITE_BASE_URL=http://ПубличныйIPАдресВМ/api > ./env/.env.prodIP

12.2. Сборка frontend части.

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

npm i && npm run buildProdIP

После успешной сборки, введите в адресную строку браузера публичный IP адрес ВМ, там должна появится frontend часть проекта, пример - 'http://ПубличныйIPАдресВМ/' (необходимо - 'http', а не 'https').

13. Установка backend части проекта и создание файлов .env и .env.prod.

13.1. Создание файла .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"

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

cd /var/www/crystal/backend && mkdir env && nano ./env/.env

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

Введите последовательно, данные ниже, в открывшемся окне, и замените примерный текст на ваши значения:

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

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

После добавления кода, нажмите последовательно - 'ctrl + x', 'y', 'Enter'.

13.2. Создание файла .env.prod.

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

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

echo PRODUCTION_STATUS=true  > ./env/.env.prodIP

13.3. Установка зависимостей в backend части проекта.

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

npm i

14. Установка базы данных MongoDB (MongoDB Community Edition) и подключение её к проекту.

Действия в этой части, будут основаны на официальной документации MongoDB.

14.1. Установка gnupg.

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

apt-get install gnupg

14.2. Импорт открытого ключа GPG MongoDB.

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

curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
    gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg \
    --dearmor

14.3. Создание файла списка, соответствующего версии Debian 12.

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

echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] http://repo.mongodb.org/apt/debian bookworm/mongodb-org/8.0 main" | tee /etc/apt/sources.list.d/mongodb-org-8.0.list

14.4. Перезагрузка локальной базы данных пакетов.

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

apt-get update

14.5. Установка последней стабильной версии MongoDB.

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

apt-get install -y mongodb-org

14.6. Этот пункт не обязательный, но вы можете закрепить текущую версию MongoDB, от дальнейших обновлений.

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

echo "mongodb-org hold" | dpkg --set-selections
echo "mongodb-org-database hold" | dpkg --set-selections
echo "mongodb-org-server hold" | dpkg --set-selections
echo "mongodb-mongosh hold" | dpkg --set-selections
echo "mongodb-org-mongos hold" | dpkg --set-selections
echo "mongodb-org-tools hold" | dpkg --set-selections

14.7. Запуск MongoDB Community Edition.

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

systemctl start mongod

Убедимся в успешном запуске, введя команду:

systemctl status mongod

При успешном запуске, должны быть подобные сообщения:

Loaded: loaded (/lib/systemd/system/mongod.service; disabled; vendor preset: enabled) Active: active (running) since Wed 2025-01-08 15:09:54 UTC; 13s ago

Далее нажмите - 'ctrl + c'.

14.8. Для того, чтобы гарантировать, что MongoDB запустится после перезапуска ВМ, введите команду:

systemctl enable mongod

Вы можете следить за состоянием процесса MongoDB на предмет ошибок или важных сообщений, наблюдая за выводом в файле - /var/log/mongodb/mongod.log.

14.9. Mongosh.

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

mongosh

Откроется консольный интерфейс для взаимодействия с базами данных, подробнее о mongosh.

В открывшимся интерфейсе введите команду:

show dbs

Вы увидите список баз данных, которые есть на данный момент, должны появится: 'admin', 'config', 'local';

Далее нажмите - 'ctrl + c'.

Важно !!!

В реальном проекте, необходимо включить авторизацию и создать администратора, поскольку порт MongoDB (по умолчанию 27017) может оказаться открытым для внешнего доступа, из-за ошибок в настройках безопасности VPC, Docker-контейнера, reverse proxy или других особенностей инфраструктуры, в результате чего, ваши данные могут быть похищены или уничтожены.
Подробные инструкции в официальной документации:
Создание пользователя для самоуправляемых развертываний.
Включение контроля доступа.

15. Запуск backend части проекта в фоновом режиме с помощью PM2.

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

cd /var/www/crystal/backend && npm install pm2@latest -g && npm run startProdIP && pm2 save && pm2 startup && pm2 status

Описание команды:

Установка PM2 - 'npm install pm2@latest -g'.

Запуск файла - 'backend/src/server.js': 'npm run startProdIP'.

Сохранение процесса PM2 - 'pm2 save'.

Перезапуск процесса PM2, после перезагрузки ВМ - 'pm2 startup'.

Статус процесса PM2 - 'pm2 status'.

Если запуск пройдет успешно, процесс с именем - 'prodIP', должен быть в статусе - 'online'.

Откройте проект в браузере, пример - 'http://ПубличныйIPАдресВМ/' (необходимо - 'http', а не "https'). Пройдите регистрацию и добавьте пост.

В дальнейшей работе с инструкцией, будет использоваться GitHub CLI в Win 11, но вы можете использовать другие методы (HTTPS, SSH). Подробнее о GitHub CLI, установщик.

16. Обновление кода проекта на ВМ, после изменения проекта на локальном ПК.

Выберите или создайте любую папку на локальном ПК, в которую будет клонирован проект из вашего репозитория - 'crystal'.

Откройте новое окно терминала и введите команду ниже:

cd C:\ИмяПапки

Пример: cd C:\GIT

Далее, клонируйте репозиторий, командой GitHub CLI:

gh repo clone ВашеИмяПользователяНаGitHub/crystal

Перейдите в папку c проектом, командой:

cd C:\GIT\crystal

Сделайте любое изменение в проекте, например в файле - 'crystal\frontend\src\index.css'

После, зафиксируйте изменения в репозитории - 'crystal', на GitHub, командой:

git add -A & git commit -m "commit" & git push -u origin main

Далее, откройте окно терминала с ВМ, обновите проект и соберите его, командой:

cd /var/www/crystal && git pull && cd /var/www/crystal/frontend && npm run buildProdIP

Проверьте изменения на сайте, через браузер.

В дальнейшем, вы можете усовершенствовать проект, действуя в последовательности: