КубКобра

КубКобра

Веб-приложение с открытым исходным кодом для создания, управления и тестирования кубиков Magic: the Gathering.

Содействие

Если вы заинтересованы в том, чтобы внести свой вклад в Cube Cobra, пожалуйста, прочтите правила внесения вклада для этого проекта.

Настраивать

Предварительные условия установки

Вам нужно будет установить NodeJS, Redis и IDE по вашему выбору (я рекомендую VSCode). Здесь вы можете найти необходимые ресурсы:

NodeJS

Узел 20

NodeJS: https://nodejs.org/en/download/

Редис

Редис-сервер:

• Windows: https://github.com/microsoftarchive/redis.
• Mac: brew install redis
• Linux: apt-get install redis

После установки Redis запустите сервер. На Mac это можно сделать проще всего: brew services start redis . Вы можете увидеть статус с помощью brew services list .

Локальный стек

Localstack обеспечивает локальную эмуляцию сервисов AWS, необходимых для запуска CubeCobra, включая S3, DynamoDB и Cloudwatch.

Вы можете следовать инструкциям по установке с сайта localstack. Рекомендуемая настройка включает запуск localstack в контейнере Docker, для которого также требуется Docker Desktop.

• Windows: загрузите и установите двоичный файл из localstack.
• Mac: brew install localstack/tap/localstack-cli
• Linux: используйте команду curl из localstack.

После установки localstack вы можете запустить сервер в фоновом режиме с помощью CLI: localstack start --detached . Вы можете увидеть статус с помощью localstack status .

Редактор кода (IDE)

VSCode (настоятельно рекомендуется, но не обязательно): https://code.visualstudio.com/ Расширение ESLint для VSCode: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint Расширение Prettier для VSCode: https ://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

VSCode (с расширением ESLint и Prettier) — рекомендуемая среда. При использовании этой настройки убедитесь, что выбранное вами рабочее пространство является корневой папкой, которую вы клонировали. Это гарантирует, что плагин ESLint сможет работать с нашими правилами проверки. Prettier автоматически применит стандартное форматирование к вашему коду. Использование этих плагинов значительно облегчит соблюдение правил линтинга и форматирования кода.

Начальная настройка

Для первой настройки вам нужно будет запустить:

yarn install && yarn build
yarn setup:local

Это будет:

• установить зависимости
• создайте код приложения для запуска сценариев установки
• запустите сценарии установки, чтобы:
  • создайте файл .env с уже установленными значениями для локального запуска приложения.
  • настроить localstack с ведром s3
  • настроить локальные файлы для сохранения приложения
  • настроить таблицы dynamodb localstack (например, пользователи, кубы, карты и т. д.)
  • загрузите данные карты из Scryfall, сохраните их в файлах и загрузите в localstack s3.

Если вы используете Windows, вам нужно будет установить bash в качестве оболочки сценария:

Вам нужно будет убедиться, что у вас где-то установлен bash , и запустить следующую команду [с вашим путем bash вместо пути ниже].

yarn config set script-shell " C: \ Program Files \ git \ bin \ bash.exe "

Бегущий КубКобра

Затем вы можете запустить программу так:

yarn start:dev

Этот скрипт будет:

• убедитесь, что localstack работает
• убедитесь, что почти все парсеры для фильтров карточек скомпилированы
• компилировать и просматривать стили scss (бутстрап)
• скомпилировать и просмотреть серверный javascript с nodemon
• запустить и посмотреть сервер разработки Webpack

Теперь вы можете открыть браузер и подключиться к приложению через http://localhost:8080.

(Несмотря на то, что в журналах узел сообщает, что он работает на порту 5000, для подключения вам следует использовать порт 8080.)

Nodemon перезапустит приложение при каждом изменении исходного файла.

После локального доступа к приложению вам необходимо будет создать новую учетную запись пользователя, используя ссылку «Сопротивляться» на панели навигации.

Переменные среды и подключение к AWS

Переменные среды заполняются из файла .env . Файл .env не зарегистрирован, поэтому сценарий установки копирует .env_EXAMPLE в .env и с некоторыми значениями по умолчанию для поддержки CubeCobra, поддерживаемого LocalStack.

При желании вы можете запустить локальный экземпляр Cube Cobra на реальных ресурсах AWS, а не на LocalStack. После настройки S3, DynamoDB и Cloudwatch с использованием вашей учетной записи AWS вы можете вставить свои учетные данные в файл .env .

Вот таблица того, как заполнять переменные окружения:

| Имя переменной | Описание | Необходимый? | | ---------------------- | -------------------------------------------------- ----------------------------------------- | --------- | --- | | AWS_ACCESS_KEY_ID | Ключ доступа к AWS для вашей учетной записи. | Да | | AWS_ENDPOINT | Базовая конечная точка, которую будет использовать AWS. Используется для указания на локальный стек, а не на размещенный AWS. | | | AWS_LOG_GROUP | Имя группы журналов AWS CloudWatch, которую нужно использовать. | Да | | AWS_LOG_STREAM | Имя используемого потока журнала AWS CloudWatch. | | | AWS_REGION | Используемый регион AWS (по умолчанию: us-east-2). | Да | | AWS_SECRET_ACCESS_KEY | Секретный ключ доступа AWS для вашей учетной записи. | Да | | КУБЕКОБРА_ВЕРСИЯ | Версия Кубической Кобры. | | | ДАННЫЕ_ВЕДРО | Имя используемого сегмента AWS S3. Вам нужно будет создать это ведро в своем аккаунте. | Да | | ДОМЕН | Доменное имя сервера. Используется для внешних перенаправлений, таких как электронные письма. | Да | | DOWNTIME_ACTIVE | Независимо от того, находится ли сайт в режиме простоя. | | | ДИНАМО_PREFIX | Префикс, используемый для таблиц DynamoDB. Вы можете оставить это значение по умолчанию | Да | | EMAIL_CONFIG_PASSWORD | Пароль для учетной записи электронной почты, который будет использоваться для отправки электронных писем. | | | EMAIL_CONFIG_USERNAME | Имя пользователя для учетной записи электронной почты, которая будет использоваться для отправки электронных писем. | | | ЕНВ | Среда для запуска Cube Cobra. | Да | | | НИТРОПАЙ_ENABLED | Включить или нет NitroPay, нашего поставщика рекламы. | | | УЗЕЛ_ENV | Среда для запуска Cube Cobra. | Да | | PATREON_CLIENT_ID | Идентификатор клиента для приложения Patreon OAuth. | | | PATREON_CLIENT_SECRET | Секрет клиента для приложения Patreon OAuth. | | | ПАТРЕОН_HOOK_SECRET | Секрет вебхука Patreon. | | | ПАТРЕОН_REDIRECT | URL-адрес перенаправления для приложения Patreon OAuth. | | | ПОРТ | Порт для запуска Cube Cobra. | Да | | REDIS_HOST | URL-адрес сервера Redis. | Да | | REDIS_SETUP | Необходимо ли настраивать сервер Redis — это необходимо для Redis, но не для elasticache. | | | СЕКРЕТ | Секретная фраза для шифрования. Вы можете оставить значение по умолчанию. | Да | | СЕССИЯ_СЕКРЕТ | Секретная фраза для шифрования сеанса. Вы можете оставить значение по умолчанию. | Да | | СЕССИЯ | Имя файла cookie сеанса. Вы можете оставить значение по умолчанию. | Да | | TCG_PLAYER_PRIVATE_KEY | Закрытый ключ для API TCGPlayer. | | | TCG_PLAYER_PUBLIC_KEY | Открытый ключ для API TCGPlayer. | | | КЭШ_ВКЛЮЧЕНО | Включить или нет кэширование. | | | АВТОСКАЛИНГ_ГРУППА | Имя группы автомасштабирования, в которой работает этот экземпляр, используемой для распределенного кэша. | | | КЭШ_СЕКРЕТ | Секрет распределенного кэша. | |

Обновление определений карт и аналитики

В сценариях начальной настройки yarn update-cards создает определения карт. Запуск этого сценария извлечет последние данные из scryfall.

Если вам нужна карточная аналитика, вы можете запустить следующий скрипт:

yarn update-all

Это будет последовательно:

• обновить историю драфтов
• обновить историю куба
• обновить словарь метаданных
• обновить карты

Концепции

Бэкэнд

API и рендеринг шаблонов

Express 4 предоставляет минималистскую веб-инфраструктуру для поддержки как рендеринга шаблонов с помощью PugJS 3, так и определения конечных точек API на основе JSON. HTML-шаблоны в основном используются для рендеринга минимальной страницы, в которую React может загрузиться с начальными реквизитами, введенными с сервера.

Карты

Мы храним все определения карт в больших предварительно обработанных файлах, так что производственным узлам нужно просто скачивать и загружать файлы, и они могут получать самые последние файлы из S3, когда они будут готовы. Мы делаем это потому, что чтение из памяти происходит гораздо быстрее, чем необходимость делать запросы к какому-либо другому сервису каждый раз, когда нам нужны данные карты.

Внешний процесс отвечает за обновление определений карты и загрузку в S3. Этот же процесс также отвечает за обновление аналитики карт и экспорт данных.

Многопользовательский драфт

Мы используем Redis для управления параллелизмом при многопользовательской разработке. Все операции Redis обрабатываются в multiplayerDrafting.js

Запланированные задания

Каждый экземпляр экспресс-сервера каждую ночь выполняет задание с использованием расписания узла для обновления карты базы данных в памяти из s3.

Скрипты Bash ( jobs/definition ) периодически выполняются на AWS для выполнения ежечасных, ежедневных и еженедельных заданий.

Карточные фильтры

Определены фильтры карточек, которые могут использоваться внешним и внутренним интерфейсом. Nearley — это набор инструментов синтаксического анализатора nodejs, который используется для генерации кода, определяющего фильтры, которые можно применять к базе данных карточек.

Внешний интерфейс

Машинопись

TypeScript 5.5 постепенно развертывается, чтобы заменить использование ванильных компонентов JS на PropTypes.

Компоненты и стиль

Компоненты предоставляются Reactstrap 9 на базе [Bootstrap v5.1][boostrap], использующего SCSS.

Компоненты обычно напрямую используют классы начальной загрузки для дополнительного стиля, но могут также использовать глобальные имена классов, определенные в общедоступных файлах CSS.