@alfalab/arui-scripts-artifacts 0.0.0-beta-20260824133302 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,277 @@
1
+ Настройки
2
+ ===
3
+
4
+ Все настройки живут в конфиге `arui-scripts-artifacts.ts` в корне проекта (см. [CLI](cli.md)):
5
+
6
+ ```ts
7
+ import { defineConfig } from '@alfalab/arui-scripts-artifacts';
8
+
9
+ export default defineConfig({
10
+ // верхний уровень — то, что общее для всех артефактов
11
+ clientOnly: false,
12
+ buildPath: '.build',
13
+
14
+ // секции — то, что относится к конкретной части сборки
15
+ docker: { registry: 'registry.example.com' },
16
+ nginx: { port: 8080 },
17
+ });
18
+ ```
19
+
20
+ Все поля опциональны: недостающие донасыщает `resolveArtifactsConfig`. Дефолты совпадают с
21
+ историческим поведением `arui-scripts`, поэтому конфиг без единой настройки соберет тот же образ,
22
+ что и `arui-scripts docker-build`.
23
+
24
+ Настройки сгруппированы по тому, к чему относятся. На верхнем уровне остается только то, что общее
25
+ для всех артефактов, — идентификация и форма самого приложения:
26
+
27
+ | Секция | За что отвечает |
28
+ | ------------------------ | ---------------------------------------------------------------------- |
29
+ | _верхний уровень_ | что и откуда собираем: `artifact`, `name`, `version`, `cwd`, `debug`, `clientOnly`, `buildPath`, `serverOutput`, `serverPort`, `assetsPath`, `publicPath` |
30
+ | [`docker`](#docker) | docker-образ: базовый образ, registry, параметры `docker build` |
31
+ | [`nginx`](#nginx) | server-блок и базовый http-блок nginx |
32
+ | [`archive`](#archive) | tar-архив |
33
+ | [`build`](#build) | хост-пайплайн: что выполняется на машине сборки перед упаковкой |
34
+ | [`packageManager`](#packagemanager) | как ставятся и чистятся зависимости |
35
+ | [`localFiles`](#localfiles) | файлы проекта, замещающие сгенерированные шаблоны |
36
+ | `templates`, `overrides` | [кастомизация шаблонов](templates.md) |
37
+ | `commands` | [свои команды сборки](commands.md#свои-команды) |
38
+
39
+ Код пакета разложен по тем же доменам: `src/docker`, `src/nginx`, `src/archive`, `src/start-script`,
40
+ `src/config`, `src/pipeline`, `src/cli`.
41
+
42
+ ## Верхний уровень
43
+
44
+ #### artifact
45
+ Что собирать: `'docker'` (по умолчанию) или `'archive'` — tar-архив с production-сборкой.
46
+ Секция `docker` при `artifact: 'archive'` не используется, и наоборот.
47
+
48
+ #### name
49
+ Имя образа/приложения. По умолчанию берется из `package.json` в `cwd`.
50
+ Переопределяется аргументом командной строки `name=...`.
51
+
52
+ #### version
53
+ Версия, она же тег образа. По умолчанию берется из `package.json` в `cwd`.
54
+ Переопределяется аргументом командной строки `version=...`.
55
+
56
+ Полное имя образа собирается как `{docker.registry}/{name}:{version}`.
57
+
58
+ #### cwd
59
+ Рабочая директория проекта. По умолчанию `process.cwd()`. Относительно нее резолвятся `package.json`,
60
+ `buildPath`, локальные файлы и временные директории.
61
+
62
+ #### debug
63
+ Режим отладки: образ не пушится (`docker.push` по умолчанию равен `!debug`), а при ошибке печатается
64
+ стек. По умолчанию `false`.
65
+
66
+ #### clientOnly
67
+ Собирается только клиентская часть — в образе поднимается nginx без nodejs-сервера. Влияет на
68
+ Dockerfile, nginx-конфиг и start.sh. По умолчанию `false`.
69
+ Подробнее про режим — в [документации arui-scripts](../../arui-scripts/docs/client-only.md).
70
+
71
+ #### buildPath
72
+ Путь к директории со сборкой приложения относительно корня проекта. По умолчанию `.build`.
73
+
74
+ #### serverOutput
75
+ Путь к серверному бандлу относительно `buildPath` — именно его запускает `start.sh`.
76
+ По умолчанию `server.js`.
77
+
78
+ #### serverPort
79
+ Порт, на котором поднимается nodejs-сервер приложения; на него nginx проксирует все, что не статика.
80
+ По умолчанию `3000`.
81
+
82
+ #### assetsPath
83
+ Директория со статикой внутри `buildPath`. По умолчанию `assets`. Из нее выводится дефолт
84
+ `publicPath`.
85
+
86
+ #### publicPath
87
+ Публичный префикс путей до статики — используется в `location`-блоках nginx-конфига.
88
+ По умолчанию `` `${assetsPath}/` `` (то есть `assets/`), как это считает `arui-scripts`.
89
+
90
+ ⚠️ Пустой `publicPath` дал бы в nginx-конфиге второй `location /`, и nginx не поднялся бы с
91
+ `duplicate location "/"`, поэтому переопределять его стоит осознанно.
92
+
93
+ ## docker
94
+
95
+ Настройки docker-образа. Не используются при `artifact: 'archive'`.
96
+
97
+ #### docker.variant
98
+ Вариант сборки: `'runtime'` (по умолчанию) — приложение собирается на хосте и результат кладется в
99
+ образ; `'compiled'` — зависимости и сборка выполняются внутри образа, слои кешируются.
100
+ От варианта зависят дефолты секции [`build`](#build).
101
+
102
+ Встроенные команды задают его сами: `docker-build` — `runtime`, `docker-build:compiled` — `compiled`.
103
+
104
+ #### docker.registry
105
+ Docker registry, к которому будет добавлено имя образа (`registry/name:version`). По умолчанию `''`
106
+ — то есть публичный registry. Переопределяется аргументом командной строки `registry=...`.
107
+
108
+ #### docker.baseImage
109
+ Базовый docker-образ (`FROM`). По умолчанию `alfabankui/arui-scripts:24.10.0-slim` — см.
110
+ [список актуальных версий](../../alpine-node-nginx/README.md).
111
+
112
+ #### docker.runFromNonRootUser
113
+ Запускать ли процессы в образе от пользователя `nginx`, а не от root. По умолчанию `true`.
114
+
115
+ #### docker.context
116
+ Контекст сборки docker — последний аргумент `docker build`. По умолчанию `'.'`.
117
+
118
+ #### docker.tempDirName
119
+ Имя временной директории, в которую складываются сгенерированные файлы (Dockerfile, nginx-конфиги,
120
+ start.sh) перед запуском `docker build`. По умолчанию `.docker-build`. Директория удаляется после
121
+ сборки.
122
+
123
+ #### docker.push
124
+ Выполнять ли `docker push` после сборки. По умолчанию `!debug`, то есть пушим всегда, кроме
125
+ режима отладки.
126
+
127
+ #### docker.platform
128
+ Управление флагом `--platform` в команде `docker build`:
129
+
130
+ - `'auto'` (по умолчанию) — историческое поведение: флаг (`linux/x86_64`) подставляется, только если
131
+ версия docker его поддерживает (>= 20.10.21). Нужно на маках с m1, где без флага docker пытается
132
+ вытянуть базовый образ под свою платформу;
133
+ - `false` — никогда не добавлять флаг;
134
+ - строка (например `'linux/amd64'`) — всегда использовать указанную платформу.
135
+
136
+ #### docker.buildArgs
137
+ Дополнительные `--build-arg` для `docker build`, объект `{ ИМЯ: значение }`. По умолчанию `{}`.
138
+
139
+ ```ts
140
+ docker: { buildArgs: { COMMIT_SHA: process.env.COMMIT_SHA ?? '' } }
141
+ ```
142
+
143
+ #### docker.addNodeModulesToDockerIgnore
144
+ Дописывать ли `node_modules` в `.dockerignore` на время сборки — нужно для compiled-образа, где
145
+ зависимости ставятся внутри. После сборки файл возвращается в исходное состояние.
146
+ По умолчанию `false`; `docker-build:compiled` включает его сам.
147
+
148
+ #### docker.deleteNpm
149
+ Удалять ли npm и связанные библиотеки (`/usr/local/bin/npm`, `/usr/local/bin/npx`,
150
+ `/usr/local/lib/node_modules/npm`) из итогового образа. Полезно, чтобы неиспользуемые пакеты не
151
+ всплывали в security-сканерах. По умолчанию `false`.
152
+
153
+ ## nginx
154
+
155
+ Настройки и server-блока, который генерируется всегда, и базового http-блока.
156
+
157
+ #### nginx.port
158
+ Порт, который nginx слушает внутри контейнера. По умолчанию `8080`.
159
+
160
+ #### nginx.rootPath
161
+ Корень, из которого nginx раздает статику. По умолчанию `/src` — статика ищется в
162
+ `${rootPath}/${buildPath}`.
163
+
164
+ #### nginx.enablePreviousVersionHeaders
165
+ Добавлять ли заголовки для предыдущей версии словаря brotli (`brotli_auto_dictionary on`).
166
+ По умолчанию `false`. Подробнее — в
167
+ [документации по словарю сжатия](../../arui-scripts/docs/compression-dictionary.md).
168
+
169
+ #### nginx.baseConf
170
+ Базовый конфиг nginx (http-блок, `/etc/nginx/nginx.conf`). По умолчанию `null` — базовый конфиг не
171
+ генерируется и не кладется в артефакт, используется тот, что лежит в базовом образе.
172
+
173
+ Любой объект включает его, `false`/`null` — выключает. Незаданные поля донасыщаются дефолтами:
174
+
175
+ | Поле | Дефолт |
176
+ | -------------------- | --------- |
177
+ | `workerProcesses` | `2` |
178
+ | `workerRlimitNoFile` | `20000` |
179
+ | `workerConnections` | `19000` |
180
+ | `eventsUse` | `'epoll'` |
181
+ | `daemon` | `'off'` |
182
+
183
+ ```ts
184
+ nginx: { baseConf: { workerProcesses: 4 } }
185
+ ```
186
+
187
+ ## archive
188
+
189
+ Настройки tar-архива. Не используются при `artifact: 'docker'`.
190
+
191
+ #### archive.name
192
+ Имя итогового tar-архива. По умолчанию `build.tar`.
193
+
194
+ #### archive.tempDirName
195
+ Имя временной директории, в которой собирается содержимое архива. По умолчанию `.archive-build`.
196
+
197
+ #### archive.additionalPaths
198
+ Дополнительные директории проекта, которые кладутся в архив рядом со сборкой. По умолчанию
199
+ `['config']`. Что попадает в архив помимо них — в [пайплайне сборки](pipeline.md#tar-архив).
200
+
201
+ ## build
202
+
203
+ Хост-пайплайн: что выполняется на машине сборки перед упаковкой артефакта. Дефолты зависят от того,
204
+ собирается ли приложение на хосте (`runtime` и любой архив) или внутри образа (`compiled`) — см.
205
+ [пайплайн сборки](pipeline.md).
206
+
207
+ #### build.cleanBuildPath
208
+ Удалять ли `buildPath` перед сборкой приложения. По умолчанию `true` для `runtime` и архива,
209
+ `false` для `compiled`.
210
+
211
+ #### build.command
212
+ Команда сборки приложения на хосте. `null`/`false` — не собирать. По умолчанию `'npm run build'` для
213
+ `runtime` и архива, `null` для `compiled` (там сборка идет внутри образа).
214
+
215
+ #### build.removeDevDependencies
216
+ Удалять ли dev-зависимости ([`packageManager.pruneCommand`](#packagemanagerprunecommand)) перед
217
+ упаковкой. По умолчанию `true` для `runtime` и архива, `false` для `compiled`.
218
+
219
+ ## packageManager
220
+
221
+ Менеджер зависимостей: как ставить production-зависимости и как выкидывать dev-зависимости.
222
+ Все поля вычисляются автоматически — задавать их нужно, только если автоопределение не подходит
223
+ (например, на машине сборки нет yarn, а команды нужны yarn-овые).
224
+
225
+ #### packageManager.useYarn
226
+ Использовать ли yarn, если он доступен. По умолчанию — по наличию `yarn.lock` в `cwd`.
227
+
228
+ #### packageManager.yarnVersion
229
+ Версия yarn: `'1'`, `'2+'` или `'unavailable'`. По умолчанию определяется автоматически по `yarn -v`
230
+ (с учетом `useYarn`).
231
+
232
+ #### packageManager.installProductionCommand
233
+ Команда установки production-зависимостей внутри образа (для `compiled`). По умолчанию выводится из
234
+ `yarnVersion`:
235
+
236
+ | `yarnVersion` | Команда |
237
+ | --------------- | --------------------------------------------------------------------------------------------- |
238
+ | `'1'` | `yarn install --production --ignore-optional --frozen-lockfile --ignore-scripts --prefer-offline` |
239
+ | `'2+'` | `yarn workspaces focus --production --all` |
240
+ | `'unavailable'` | `npm install --production` |
241
+
242
+ #### packageManager.pruneCommand
243
+ Команда очистки dev-зависимостей на хосте перед упаковкой артефакта. По умолчанию выводится из
244
+ `yarnVersion` (для `unavailable` — `npm prune --production`), а в режиме `clientOnly` заменяется на
245
+ заглушку: чистить нечего, `node_modules` в артефакт не попадает.
246
+
247
+ #### packageManager.yarnBinSymlinkCommand
248
+ Команда создания symlink на бинарник yarn внутри образа (для `compiled`). По умолчанию
249
+ подставляется для yarn 2+ с `yarnPath` в `.yarnrc.yml` — чтобы `yarn` был доступен в PATH внутри
250
+ образа, где он не установлен глобально. Иначе — пустая строка.
251
+
252
+ ## localFiles
253
+
254
+ Файлы проекта, которые используются вместо сгенерированных шаблонов. CLI сам находит лежащие в корне
255
+ проекта `Dockerfile`, `start.sh`, `nginx.conf` и `base-nginx.conf`; явно заданные пути имеют
256
+ приоритет над автодетектом. Подробнее — в [кастомизации шаблонов](templates.md#локальные-файлы).
257
+
258
+ #### localFiles.dockerfile
259
+ Путь до своего `Dockerfile`. По умолчанию `null` (автодетект в корне проекта).
260
+
261
+ #### localFiles.startScript
262
+ Путь до своего `start.sh`. По умолчанию `null`.
263
+
264
+ #### localFiles.nginxConf
265
+ Путь до своего server-блока (`nginx.conf`). По умолчанию `null`.
266
+
267
+ #### localFiles.nginxBaseConf
268
+ Путь до своего базового http-блока (`base-nginx.conf`). Используется, только если включен
269
+ [`nginx.baseConf`](#nginxbaseconf). По умолчанию `null`.
270
+
271
+ #### localFiles.allowDockerfile
272
+ Разрешена ли подмена Dockerfile локальным файлом. По умолчанию `true`; `docker-build:compiled`
273
+ выключает — образ собирает зависимости сам, и чужой Dockerfile это ломает.
274
+
275
+ #### localFiles.allowStartScript
276
+ Разрешена ли подмена `start.sh` локальным файлом. По умолчанию `true`, у `docker-build:compiled` —
277
+ `false`.
@@ -0,0 +1,128 @@
1
+ Кастомизация файлов артефакта
2
+ ===
3
+
4
+ В артефакт кладутся четыре сгенерированных файла:
5
+
6
+ | Ключ шаблона | Файл | Что это |
7
+ | ------------------- | ------------------------------- | ---------------------------------------------- |
8
+ | `dockerfile` | `Dockerfile` | «сырой» образ: сборка на хосте |
9
+ | `dockerfileCompiled`| `Dockerfile` | compiled-образ: сборка внутри образа |
10
+ | `nginxConf` | `nginx.conf` | server-блок nginx |
11
+ | `baseNginxConf` | `base-nginx.conf` | базовый http-блок (`/etc/nginx/nginx.conf`) |
12
+ | `startScript` | `start.sh` | entrypoint артефакта |
13
+
14
+ ⚠️ В `arui-scripts` имена `nginx` и `nginxConf` исторически перепутаны: `nginx` — это server-блок, а
15
+ `nginxConf` — базовый конфиг. Здесь они названы по смыслу, поэтому **`nginxConf` в двух пакетах
16
+ означает разные файлы**. Переносить оверрайды по [таблице миграции](migration.md), а не по
17
+ совпадению имен.
18
+
19
+ Каждый файл настраивается на четырех уровнях, по возрастанию приоритета:
20
+
21
+ 1. **[Опции](settings.md)** — секции `docker`, `nginx` и верхнеуровневые `clientOnly`, `buildPath`,
22
+ `serverOutput`, `publicPath` и остальные.
23
+ 2. **`templates`** — полная замена рендерера: `(config) => string`.
24
+ 3. **`overrides`** — точечная функция поверх сгенерированного: `(generated, config) => string`.
25
+ 4. **[Локальные файлы](#локальные-файлы)** — `Dockerfile`, `start.sh`, `nginx.conf`,
26
+ `base-nginx.conf` в корне проекта.
27
+
28
+ Начинать стоит с опций: почти все, что обычно правят руками, уже вынесено в настройки.
29
+
30
+ ## templates
31
+
32
+ Полная замена генерации файла. Функция получает донасыщенный конфиг и возвращает содержимое файла:
33
+
34
+ ```ts
35
+ import { defineConfig } from '@alfalab/arui-scripts-artifacts';
36
+
37
+ export default defineConfig({
38
+ templates: {
39
+ nginxConf: (config) => `
40
+ client_max_body_size 20m;
41
+
42
+ server {
43
+ listen ${config.nginx.port};
44
+ location = /health { return 200 ''; }
45
+ location / { proxy_pass http://127.0.0.1:${config.serverPort}; }
46
+ }`,
47
+ },
48
+ });
49
+ ```
50
+
51
+ Рендереры по умолчанию (`renderDockerfile`, `renderDockerfileCompiled`, `renderNginxConf`,
52
+ `renderBaseNginxConf`, `renderStartScript`) экспортируются наружу — их можно вызывать и оборачивать
53
+ из своих шаблонов:
54
+
55
+ ```ts
56
+ import { defineConfig, renderNginxConf } from '@alfalab/arui-scripts-artifacts';
57
+
58
+ export default defineConfig({
59
+ templates: {
60
+ nginxConf: (config) => `${renderNginxConf(config)}\n# наши правила\n`,
61
+ },
62
+ });
63
+ ```
64
+
65
+ ## overrides
66
+
67
+ Точечная правка сгенерированного содержимого — когда менять файл целиком незачем:
68
+
69
+ ```ts
70
+ import { defineConfig } from '@alfalab/arui-scripts-artifacts';
71
+
72
+ export default defineConfig({
73
+ overrides: {
74
+ dockerfile: (generated) => `${generated}\nLABEL team="web"`,
75
+ nginxConf: (generated, config) =>
76
+ config.clientOnly ? generated : `${generated}\n# proxy tuning\n`,
77
+ },
78
+ });
79
+ ```
80
+
81
+ Оверрайд применяется после `templates`, поэтому видит результат своего рендерера, а не дефолтного.
82
+ Базовый http-блок при выключенном `nginx.baseConf` не рендерится вовсе — оверрайд `baseNginxConf`
83
+ в этом случае не вызывается.
84
+
85
+ Секции `templates` и `overrides` сливаются по ключам, так что команда может переопределить один
86
+ шаблон, оставив остальные от верхнего уровня, — см. [Команды](commands.md#как-складываются-настройки).
87
+
88
+ ## Локальные файлы
89
+
90
+ Файл в корне проекта побеждает и шаблон, и оверрайд: содержимое берется как есть.
91
+ CLI находит `Dockerfile`, `start.sh`, `nginx.conf` и `base-nginx.conf` сам, пути можно задать явно
92
+ через [`localFiles`](settings.md#localfiles).
93
+
94
+ Примеры того, что переопределяете, лежат прямо в пакете:
95
+ [dockerfile.template.ts](../src/docker/templates/dockerfile.template.ts),
96
+ [dockerfile-compiled.template.ts](../src/docker/templates/dockerfile-compiled.template.ts),
97
+ [nginx.conf.template.ts](../src/nginx/templates/nginx.conf.template.ts),
98
+ [base-nginx.conf.template.ts](../src/nginx/templates/base-nginx.conf.template.ts),
99
+ [start.template.ts](../src/start-script/start.template.ts).
100
+
101
+ Для `docker-build:compiled` подмена `Dockerfile` и `start.sh` запрещена: образ ставит зависимости и
102
+ собирает приложение сам, и чужой Dockerfile это ломает. Запрет снимается флагами
103
+ `localFiles.allowDockerfile` и `localFiles.allowStartScript`.
104
+
105
+ ## Env-переменные в nginx.conf
106
+
107
+ Конфигурация nginx прогоняется при старте контейнера через
108
+ [envsubst](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html), поэтому
109
+ часть настроек можно не зашивать в образ, а передавать переменными окружения:
110
+
111
+ ```nginx
112
+ server {
113
+ listen 8080;
114
+ server_name ${SERVICE_NAME};
115
+ }
116
+ ```
117
+
118
+ ```bash
119
+ docker run my-awesome-app --env SERVICE_NAME=my-app
120
+ ```
121
+
122
+ **Важно.** Чтобы специальные переменные nginx (`$proxy_add_x_forwarded_for` и подобные) не
123
+ превратились в пустые строки, перед запуском `envsubst` они заменяются на `~~proxy_add_x_forwarded_for~~`,
124
+ а после — возвращаются в исходный вид. Так что envsubst подставляет **только** переменные,
125
+ записанные как `${MY_VAR}`.
126
+
127
+ Если используете свой базовый образ — убедитесь, что в нем есть `envsubst`. Для alpine он входит в
128
+ пакет [`gettext`](https://pkgs.alpinelinux.org/contents?branch=edge&name=gettext&arch=x86&repo=main).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alfalab/arui-scripts-artifacts",
3
- "version": "0.0.0-beta-20260824133302",
3
+ "version": "1.0.0",
4
4
  "description": "CLI и библиотека для сборки артефактов поставки приложений на arui-scripts: docker-образ и tar-архив с генерируемыми Dockerfile, nginx-конфигом и start-скриптом",
5
5
  "main": "./build/cjs/index.js",
6
6
  "module": "./build/index.js",
@@ -39,7 +39,7 @@
39
39
  "jiti": "^2.4.2",
40
40
  "semver": "^7.5.4",
41
41
  "shelljs": "0.8.5",
42
- "tar": "7.5.11"
42
+ "tar": "7.5.21"
43
43
  },
44
44
  "devDependencies": {
45
45
  "@types/fs-extra": "^9.0.13",