Сборка и требования

Требования:

• Go 1.26+
• PostgreSQL, Redis
• Make

Локальная сборка

# Установка зависимостей
go mod download

# Линт/тест/сборка
go vet ./...
go test ./... -race
go build ./...

Линтеры

Используется golangci-lint v2.10.1 с дополнительными линтерами:

# Установка
make install-lint

# Полный прогон
make lint

# Быстрый (только app + domain)
make lint-fast

# Архитектурная проверка (domain не импортирует infra/app)
make lint-arch

Включены линтеры: gosec (безопасность), bodyclose (закрытие тел HTTP-ответов), noctx (передача context в HTTP-запросы). Конфигурация — .golangci.yml.

Сканирование уязвимостей

make vulncheck

Запускает govulncheck ./... — проверяет зависимости на известные CVE.

CI (.gitlab-ci.yml)

Этапы пайплайна:

Этап	Job	Когда
check	lint (golangci-lint), docs (redocly), test (go test + coverage), integration (Postgres+Redis)	Каждый push
security	govulncheck	Каждый push
build	build (go build)	Push без тега
build	build-release (bundle + upload в Package Registry)	Push с тегом

На push с тегом job build-release собирает deployment-бандл и загружает его в GitLab Package Registry (Generic Packages).

Deployment Bundle

Бандл — самодостаточный архив для деплоя на сервер (Go на сервере не нужен):

# Для текущей ОС
make bundle

# Для Linux (серверы)
make bundle-linux

# С явной версией
VERSION=1.2.3 make bundle

# Произвольная платформа
make bundle GOOS=linux GOARCH=arm64

Содержимое бандла:

marv-VERSION-OS-ARCH/
├── bin/
│   ├── marv                # основной сервер
│   ├── hgoose              # утилита миграций БД (goose v3)
│   └── config-migrator     # конвертер legacy-конфигов
├── scripts/
│   ├── deploy.sh           # управление (run, migrate, version, ...)
│   └── marv.service.template # шаблон systemd unit
├── migrations/
│   └── *.sql               # SQL-миграции
└── config/
    ├── config.example.yml  # пример конфигурации
    ├── bots.example.json   # пример конфигурации ботов
    ├── products.example.json # пример конфигурации продуктов
    └── .env.example        # пример переменных окружения

Параметры сборки:

• CGO_ENABLED=0 — статическая линковка
• -tags=go_json — ускоренный JSON через go_json
• -ldflags="-s -w -X ...AppVersion=VERSION" — инъекция версии, strip debug info

Деплой на сервер

Рекомендуемый подход — через отдельный game-репозиторий с конфигами и версией. См. Game Repository workflow.

Автоматическое скачивание (рекомендуется)

Скрипт scripts/fetch-release.sh автоматически скачивает и распаковывает нужную версию бандла из GitLab Generic Packages.

Настройка Deploy Token (однократно):

1. Перейдите в GitLab → Settings → Repository → Deploy tokens
2. Создайте токен:
   • Name: marv-deploy (или любое имя)
   • Scopes: read_package_registry
   • Expiration: по усмотрению (или без ограничения)
3. Сохраните username и token — token показывается только один раз

Настройка на сервере:

# Добавьте в ~/.bashrc, ~/.profile или /etc/environment
export MARV_DEPLOY_TOKEN="<username>:<token>"

# Создайте файл версии
echo "v2.0.3" > .marv-version

Скачивание и установка:

# Скачать версию из .marv-version
./scripts/fetch-release.sh

# Скачать конкретную версию
MARV_VERSION=v2.0.3 ./scripts/fetch-release.sh

# Проверить версии (без скачивания)
./scripts/fetch-release.sh --check

Типы аутентификации (используется первый найденный):

Переменная	Тип	Формат	Назначение
MARV_DEPLOY_TOKEN	Deploy Token	username:token	Серверы (рекомендуется)
GITLAB_TOKEN	Personal Access Token	glpat-xxx	Разработчики
CI_JOB_TOKEN	CI Job Token	автоматически	GitLab CI

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

Переменная	Умолчание	Описание
GITLAB_URL	https://gitlab.com	Базовый URL GitLab
GITLAB_PROJECT_ID	22503710	Числовой ID проекта
MARV_PLATFORM	linux-amd64	Платформа бандла
INSTALL_DIR	./marv	Директория для установки
VERSION_FILE	.marv-version	Путь к файлу с версией

Пример обновления на сервере:

# Обновить версию
echo "v2.1.0" > .marv-version

# Скачать и распаковать
./scripts/fetch-release.sh

# Применить миграции и перезапустить
./marv/scripts/deploy.sh migrate
./marv/scripts/deploy.sh run

Ручной деплой

# 1. Распаковать бандл
tar -xzf marv-1.2.3-linux-amd64.tar.gz
cd marv-1.2.3-linux-amd64

# 2. Подготовить конфиг
cp config/config.example.yml config/config.release.yml
# Заполнить значения, либо использовать переменные окружения (config/.env.example)

# 3. Применить миграции
./scripts/deploy.sh migrate

# 4. Запустить сервер
./scripts/deploy.sh run

deploy.sh

Скрипт-помощник для управления бандлом на сервере. Входит в состав бандла.

Команда	Описание
migrate	Применить все миграции
migrate-status	Статус миграций
migrate-down	Откатить одну миграцию
config-migrate <file>	Мигрировать legacy-конфиг в новый формат
run	Запустить сервер (GIN_MODE=release)
version	Версия бинарников

./scripts/deploy.sh migrate     # миграции
./scripts/deploy.sh run         # запуск
./scripts/deploy.sh version     # версия

Docker

Dockerfile (multi-stage build):

# Сборка образа
docker build -t marv:latest --build-arg VERSION=1.2.3 .

# Запуск
docker run -p 8080:8080 -v ./config:/app/config marv:latest

Docker Compose (локальная разработка):

docker-compose up -d

Поднимает marv + PostgreSQL 17 + Redis 7 с health-checks и пробросом портов.

Запуск

# Из исходников
go run ./cmd/marv

# Из бинарника
./marv

Перед деплоем:

1. Применить миграции (hgoose up или ./scripts/deploy.sh migrate)
2. Заполнить конфиг или переменные окружения
3. Dev: PostgreSQL и Redis локальные. Release: PostgreSQL — отдельный сервер, Redis — обычно локальный