# HY2XS production builder

Этот каталог содержит production builder для HY2XS.

Builder собирает один переносимый install-archive:

```text
dist/hy2xs-install-<version>.tar.gz
```

Этот архив переносится на production server, распаковывается и устанавливается через [`install.sh`](../../package/install.sh).

На production server не должно быть сборки из исходников: без `go build`, без `bun install`, без `pnpm install`, без frontend build и без TypeScript transpilation.

## Что где лежит

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

- [`tools/build/build.sh`](build.sh) — главный entrypoint сборки.
- [`tools/build/lib/deps.sh`](lib/deps.sh) — проверка Debian/amd64, установка build dependencies, установка Go/Bun/Node.js/pnpm.
- [`tools/build/lib/package.sh`](lib/package.sh) — сборка orchestrator, сборка HY2XS admin, создание stage directory и tar.gz архива.
- [`tools/build/lib/verify.sh`](lib/verify.sh) — проверка структуры репозитория и итогового архива.
- [`tools/build/hysteria-lock.env`](hysteria-lock.env) — pinned версия, URL и SHA256 upstream Hysteria2 binary.
- [`orchestrator`](../../orchestrator) — TypeScript/Bun install-only orchestrator.
- [`apps`](../../apps) — HY2XS admin: Go backend и Vue frontend.
- [`package`](../../package) — skeleton будущего install package: `install.sh`, templates, systemd units, default config.
- [`dist`](../../dist) — итоговые архивы. Создаётся builder'ом, в git обычно не хранится.
- [`.toolchain`](../../.toolchain) — локальный toolchain builder'а. Создаётся автоматически, в git не хранится.

## Требования к build machine

Production build поддерживается только на:

- Debian 13;
- amd64 / x86_64;
- root или пользователь с `sudo`;
- доступ в интернет.

Нужен outbound HTTPS/DNS до:

- Debian apt repositories;
- `go.dev`;
- `github.com`;
- `nodejs.org`;
- npm registry.

Windows и macOS можно использовать для редактирования исходников, но финальную production-сборку надо делать на Debian 13 amd64.

## Что builder делает сам

При запуске builder:

1. Проверяет, что host — Debian 13 amd64.
2. Проверяет структуру репозитория.
3. Устанавливает недостающие системные build dependencies через `apt-get`.
4. Проверяет или скачивает локальные версии:
   - Go `1.21.13`;
   - Bun `1.3.13`;
   - Node.js `20.19.0`;
   - pnpm `9.15.9`.
5. Собирает install-only orchestrator в standalone binary.
6. Собирает frontend HY2XS admin.
7. Собирает backend HY2XS admin в Linux amd64 binary.
8. Копирует package skeleton.
9. Записывает metadata и checksums.
10. Создаёт `dist/hy2xs-install-<version>.tar.gz`.
11. Проверяет, что архив содержит обязательные файлы.

## Важное про Bun и старые CPU

Bun имеет два Linux x64 artifact'а:

- `bun-linux-x64` — обычный build;
- `bun-linux-x64-baseline` — build для CPU без AVX2.

Если CPU не поддерживает AVX2, обычный Bun может падать с `Illegal instruction`.

Builder автоматически проверяет [`/proc/cpuinfo`](../../fix17.txt).

По умолчанию:

```bash
BUN_FLAVOR=auto
```

Логика:

- если CPU поддерживает AVX2, используется `bun-linux-x64`;
- если CPU не поддерживает AVX2, используется `bun-linux-x64-baseline`.

Можно принудительно задать flavor:

```bash
BUN_FLAVOR=x64 ./tools/build/build.sh
```

или:

```bash
BUN_FLAVOR=x64-baseline ./tools/build/build.sh
```

## Запуск

Из корня репозитория:

```bash
./tools/build/build.sh
```

С явной версией и build id:

```bash
PACKAGE_VERSION=0.2.1 \
BUILD_ID=prod-$(date -u +%Y%m%dT%H%M%SZ) \
./tools/build/build.sh
```

## Проверка результата

Проверка архива:

```bash
ls -lh dist/hy2xs-install-0.2.1.tar.gz
sha256sum dist/hy2xs-install-0.2.1.tar.gz | tee dist/hy2xs-install-0.2.1.tar.gz.sha256
```

Проверка обязательных файлов:

```bash
tar -tzf dist/hy2xs-install-0.2.1.tar.gz | grep -E '^(hy2xs-install/install.sh|hy2xs-install/orchestrator/hy2xs-orchestrator|hy2xs-install/ui/hy2xs-admin/hy2xs-admin|hy2xs-install/metadata/checksums.txt)$'
```

Проверка metadata:

```bash
tar -xOzf dist/hy2xs-install-0.2.1.tar.gz hy2xs-install/metadata/package.env
```

## When to update orchestrator/bun.lock

Do not regenerate [`orchestrator/bun.lock`](../../orchestrator/bun.lock) during production builds.

Update and commit [`orchestrator/bun.lock`](../../orchestrator/bun.lock) only when:

- [`orchestrator/package.json`](../../orchestrator/package.json) changes;
- `BUN_REQUIRED` changes in [`tools/build/lib/deps.sh`](lib/deps.sh);
- orchestrator dependencies are intentionally upgraded.

Production builder always runs:

```bash
bun install --frozen-lockfile
```

If this command fails, fix and commit the lockfile in source control. Do not remove `--frozen-lockfile`.

## Frontend lockfile discipline

Do not regenerate frontend lock data during routine production builds.

For frontend package management:

- [`apps/frontend/package.json`](../../apps/frontend/package.json) declares `"packageManager": "pnpm@9.15.9"`;
- builder uses pinned pnpm `9.15.9` from [`PNPM_REQUIRED`](lib/deps.sh);
- production frontend install path is always:

```bash
pnpm install --frozen-lockfile
```

If frozen install fails, update dependencies intentionally in source control and commit lockfile changes. Do not remove `--frozen-lockfile` from build flow.

## Полезные переменные

- `PACKAGE_VERSION=0.2.1`
- `BUILD_ID=prod-$(date -u +%Y%m%dT%H%M%SZ)`
- `BUN_FLAVOR=auto|x64|x64-baseline`
- `FRONTEND_NODE_OLD_SPACE_SIZE=2048` (default memory limit for frontend build step)
- `TOOLCHAIN_DIR=/custom/path/.toolchain`
- `VERIFY_TOOLCHAIN_CHECKSUMS=true`

По умолчанию `VERIFY_TOOLCHAIN_CHECKSUMS=true` в [`tools/build/lib/deps.sh`](tools/build/lib/deps.sh), поэтому для production-сборки обязательно передавать контрольные суммы:

- `GO_ARCHIVE_SHA256=<sha256>`
- `NODE_ARCHIVE_SHA256=<sha256>`
- `BUN_ARCHIVE_SHA256=<sha256>`

## Frontend memory policy

Builder applies a safe default Node.js heap limit for frontend build inside [`bundle_ui()`](lib/package.sh):

```bash
--max-old-space-size=2048
```

Override options:

- adjust default value for this policy:

```bash
FRONTEND_NODE_OLD_SPACE_SIZE=3072 ./tools/build/build.sh
```

- or provide full custom Node options (if `--max-old-space-size` is already set there, builder will not append another one):

```bash
NODE_OPTIONS="--max-old-space-size=3072" ./tools/build/build.sh
```

## Диагностика

Проверить AVX2:

```bash
grep -m1 '^flags' /proc/cpuinfo | grep -qw avx2 && echo 'CPU has AVX2' || echo 'CPU has NO AVX2; Bun baseline is required'
```

Проверить Bun:

```bash
.toolchain/bun/bin/bun --version
echo "bun_exit=$?"
```

Если есть `Illegal instruction`, удалите старый Bun и пересоберите:

```bash
rm -rf .toolchain/bun .toolchain/bun-tmp
rm -f .toolchain/downloads/bun-linux-x64-*.zip
rm -f .toolchain/downloads/bun-linux-x64-baseline-*.zip
PACKAGE_VERSION=0.2.1 ./tools/build/build.sh
```

Проверить shell syntax:

```bash
bash -n tools/build/build.sh
bash -n tools/build/lib/common.sh
bash -n tools/build/lib/deps.sh
bash -n tools/build/lib/package.sh
bash -n tools/build/lib/verify.sh
```