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

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

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

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

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

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

• MongoDB v8.0.4.
• Express.js v4.21.2.
• React v19.0.0.
• Node.js v23.6.1.
• PM2 v5.4.3.
• PNPM v10.5.2.
• Vite v6.1.0.

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

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.

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

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

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

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

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

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

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

Название — сrystal.

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

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

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

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

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

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

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

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

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

0.0.0.0/0

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

HTTPS IPv4

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

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

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

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

All egress IPv4

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

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

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

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

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

Название — сrystal.

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

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

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

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

Образ:

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

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

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

vCPU — 2

RAM — 4

Диски:

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

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

Тип — SSD

Размер — 20ГБ

Настройки

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

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

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

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

Группы безопасности — выберите ранее созданную группу безопасности — ‘сrystal’.

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

Имя хоста — 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.

В дальнейшем при вводе команд, может появляться вопрос — ‘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 командой:

curl -fsSL https://deb.nodesource.com/setup_23.x | bash - && \apt-get install -y nodejs && nodejs -v

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. Установка PNPM.

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

curl -fsSL https://get.pnpm.io/install.sh | sh - && source /root/.bashrc && pnpm -v

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

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

pnpm i && pnpm buildProdIP

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

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

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

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

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

Далее, необходимо задать значение переменной — ‘JWT_SECRET_KEY’, вы можете сами ввести значение из букв и цифр, или сгенировать его в различных сервисах, например в Nano ID.

Пример того, как может выглядеть JWT_SECRET_KEY — ‘IA9bVtK6yQu1hpG2TCKCrC5h0VJmRZcZlrnZ’.

При регистрации пользователя с 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 части проекта.

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

pnpm i

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

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

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

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

sudo apt-get install gnupg curl

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

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

curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
    sudo 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" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

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

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

sudo apt-get update

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

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

sudo apt-get install -y mongodb-org

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

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

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

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

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

sudo systemctl start mongod

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

sudo 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 запустится после перезапуска ВМ, введите команду:

sudo systemctl enable mongod

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

14.9. Mongosh.

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

mongosh

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

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

show dbs

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

Далее нажмите — ‘ctrl + c’.

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

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

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

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

Установка PM2 — ‘sudo npm install pm2@latest -g’.

Запуск файла — ‘backend/src/server.js’: ‘pnpm startProd’.

Сохранение процесса 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 && pnpm buildProdIP

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

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