@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.
- package/.turbo/turbo-test.log +8 -7
- package/CHANGELOG.md +4 -4
- package/README.md +14 -256
- package/build/cjs/config/index.js +2 -0
- package/build/cjs/config/types.d.ts +10 -0
- package/build/cjs/docker/constants.d.ts +2 -0
- package/build/cjs/docker/constants.js +3 -1
- package/build/cjs/docker/index.d.ts +1 -1
- package/build/cjs/docker/index.js +2 -1
- package/build/cjs/docker/templates/dockerfile-compiled.template.js +6 -2
- package/build/cjs/docker/templates/dockerfile.template.js +4 -1
- package/build/cjs/index.d.ts +1 -1
- package/build/cjs/index.js +3 -1
- package/build/cjs/utils/yarn.d.ts +16 -0
- package/build/cjs/utils/yarn.js +40 -0
- package/build/config/index.js +3 -1
- package/build/config/types.d.ts +10 -0
- package/build/docker/constants.d.ts +2 -0
- package/build/docker/constants.js +2 -0
- package/build/docker/index.d.ts +1 -1
- package/build/docker/index.js +1 -1
- package/build/docker/templates/dockerfile-compiled.template.js +6 -2
- package/build/docker/templates/dockerfile.template.js +4 -1
- package/build/index.d.ts +1 -1
- package/build/index.js +1 -1
- package/build/utils/yarn.d.ts +16 -0
- package/build/utils/yarn.js +38 -0
- package/docs/api.md +118 -0
- package/docs/cli.md +96 -0
- package/docs/commands.md +87 -0
- package/docs/migration.md +86 -0
- package/docs/pipeline.md +62 -0
- package/docs/settings.md +277 -0
- package/docs/templates.md +128 -0
- package/package.json +2 -2
|
@@ -17,3 +17,5 @@ export const DOCKERIGNORE_FILENAME = '.dockerignore';
|
|
|
17
17
|
export const PLATFORM_FLAG_MIN_DOCKER_VERSION = '>=20.10.21';
|
|
18
18
|
/** Значение флага `--platform`, которое подставляется при `platform: 'auto'` на новых версиях docker. */
|
|
19
19
|
export const DEFAULT_PLATFORM = 'linux/x86_64';
|
|
20
|
+
/** Команда удаления npm и связанных библиотек из образа (`docker.deleteNpm`). */
|
|
21
|
+
export const DELETE_NPM_COMMAND = 'RUN rm -rf /usr/local/bin/npm /usr/local/bin/npx /usr/local/lib/node_modules/npm';
|
package/build/docker/index.d.ts
CHANGED
|
@@ -4,4 +4,4 @@ export { dockerVersionSatisfies, getDockerBuildCommand, getPlatformFlag } from '
|
|
|
4
4
|
export { prepareFilesForDocker, type PrepareFilesForDockerResult } from './prepare-files';
|
|
5
5
|
export { renderDockerfile } from './templates/dockerfile.template';
|
|
6
6
|
export { renderDockerfileCompiled } from './templates/dockerfile-compiled.template';
|
|
7
|
-
export { DEFAULT_BASE_DOCKER_IMAGE, DEFAULT_PLATFORM, DEFAULT_TEMP_DIR_NAME, DOCKERFILE_FILENAME, DOCKERIGNORE_FILENAME, PLATFORM_FLAG_MIN_DOCKER_VERSION, } from './constants';
|
|
7
|
+
export { DEFAULT_BASE_DOCKER_IMAGE, DEFAULT_PLATFORM, DEFAULT_TEMP_DIR_NAME, DELETE_NPM_COMMAND, DOCKERFILE_FILENAME, DOCKERIGNORE_FILENAME, PLATFORM_FLAG_MIN_DOCKER_VERSION, } from './constants';
|
package/build/docker/index.js
CHANGED
|
@@ -4,4 +4,4 @@ export { dockerVersionSatisfies, getDockerBuildCommand, getPlatformFlag } from '
|
|
|
4
4
|
export { prepareFilesForDocker } from './prepare-files';
|
|
5
5
|
export { renderDockerfile } from './templates/dockerfile.template';
|
|
6
6
|
export { renderDockerfileCompiled } from './templates/dockerfile-compiled.template';
|
|
7
|
-
export { DEFAULT_BASE_DOCKER_IMAGE, DEFAULT_PLATFORM, DEFAULT_TEMP_DIR_NAME, DOCKERFILE_FILENAME, DOCKERIGNORE_FILENAME, PLATFORM_FLAG_MIN_DOCKER_VERSION, } from './constants';
|
|
7
|
+
export { DEFAULT_BASE_DOCKER_IMAGE, DEFAULT_PLATFORM, DEFAULT_TEMP_DIR_NAME, DELETE_NPM_COMMAND, DOCKERFILE_FILENAME, DOCKERIGNORE_FILENAME, PLATFORM_FLAG_MIN_DOCKER_VERSION, } from './constants';
|
|
@@ -1,10 +1,11 @@
|
|
|
1
|
+
import { DELETE_NPM_COMMAND } from '../constants';
|
|
1
2
|
/**
|
|
2
3
|
* Dockerfile для compiled-образа: зависимости и сборка приложения происходят внутри образа, что
|
|
3
4
|
* позволяет кешировать установку зависимостей на уровне docker-слоев.
|
|
4
5
|
*/
|
|
5
6
|
export function renderDockerfileCompiled(config) {
|
|
6
7
|
const { docker, nginx, packageManager } = config;
|
|
7
|
-
const { yarnVersion, installProductionCommand } = packageManager;
|
|
8
|
+
const { yarnVersion, installProductionCommand, yarnBinSymlinkCommand } = packageManager;
|
|
8
9
|
// В зависимости от используемого менеджера зависимостей для их установки нужно копировать разный
|
|
9
10
|
// набор файлов
|
|
10
11
|
const filesRequiredToInstallDependencies = [
|
|
@@ -32,11 +33,14 @@ ${filesRequiredToInstallDependencies
|
|
|
32
33
|
.map((file) => `ADD --chown=nginx:nginx ${file} /src/${file}`)
|
|
33
34
|
.join('\n')}
|
|
34
35
|
|
|
35
|
-
RUN ${installProductionCommand} && \\
|
|
36
|
+
RUN ${yarnBinSymlinkCommand}${installProductionCommand} && \\
|
|
36
37
|
${yarnVersion === 'unavailable' ? 'npm cache clean --force' : 'yarn cache clean --all'}
|
|
37
38
|
|
|
38
39
|
ADD --chown=nginx:nginx . /src
|
|
39
40
|
|
|
41
|
+
# При необходимости удаляем npm и связанные библиотеки из образа
|
|
42
|
+
${docker.deleteNpm ? DELETE_NPM_COMMAND : ''}
|
|
43
|
+
|
|
40
44
|
# Создаем директории для nginx и выставляем правильные права
|
|
41
45
|
RUN mkdir -p /var/lib/nginx && \
|
|
42
46
|
chown -R nginx:nginx /var/lib/nginx && \
|
|
@@ -1,9 +1,10 @@
|
|
|
1
|
+
import { DELETE_NPM_COMMAND } from '../constants';
|
|
1
2
|
/**
|
|
2
3
|
* Dockerfile для «сырого» образа: приложение собирается на хосте, в образ кладется результат сборки.
|
|
3
4
|
*/
|
|
4
5
|
export function renderDockerfile(config) {
|
|
5
6
|
const { clientOnly, buildPath, docker, nginx } = config;
|
|
6
|
-
const { runFromNonRootUser, baseImage } = docker;
|
|
7
|
+
const { runFromNonRootUser, baseImage, deleteNpm } = docker;
|
|
7
8
|
const appPathToAdd = clientOnly ? buildPath : '.';
|
|
8
9
|
const appTargetPath = clientOnly ? `/src/${buildPath}` : '/src';
|
|
9
10
|
const nginxConfTargetLocation = clientOnly
|
|
@@ -32,6 +33,8 @@ ADD $START_SH_LOCATION /src/start.sh
|
|
|
32
33
|
ADD $NGINX_CONF_LOCATION ${nginxConfTargetLocation}
|
|
33
34
|
${nginx.baseConf ? 'ADD $NGINX_BASE_CONF_LOCATION /etc/nginx/nginx.conf' : ''}
|
|
34
35
|
|
|
36
|
+
${deleteNpm ? DELETE_NPM_COMMAND : ''}
|
|
37
|
+
|
|
35
38
|
${nginxNonRootPart}
|
|
36
39
|
|
|
37
40
|
${runFromNonRootUser
|
package/build/index.d.ts
CHANGED
|
@@ -12,4 +12,4 @@ export * from './start-script';
|
|
|
12
12
|
export * from './cli';
|
|
13
13
|
export { exec, ExecError } from './utils/exec';
|
|
14
14
|
export { shellQuote } from './utils/shell';
|
|
15
|
-
export { detectUseYarn, getInstallProductionCommand, getPruningCommand, getYarnVersion, } from './utils/yarn';
|
|
15
|
+
export { detectUseYarn, getInstallProductionCommand, getPruningCommand, getYarnBinSymlinkCommand, getYarnPathFromRc, getYarnVersion, } from './utils/yarn';
|
package/build/index.js
CHANGED
|
@@ -17,4 +17,4 @@ export * from './cli';
|
|
|
17
17
|
/* Утилиты */
|
|
18
18
|
export { exec, ExecError } from './utils/exec';
|
|
19
19
|
export { shellQuote } from './utils/shell';
|
|
20
|
-
export { detectUseYarn, getInstallProductionCommand, getPruningCommand, getYarnVersion, } from './utils/yarn';
|
|
20
|
+
export { detectUseYarn, getInstallProductionCommand, getPruningCommand, getYarnBinSymlinkCommand, getYarnPathFromRc, getYarnVersion, } from './utils/yarn';
|
package/build/utils/yarn.d.ts
CHANGED
|
@@ -10,6 +10,22 @@ export declare function getYarnVersion({ useYarn }: GetYarnVersionParams): YarnV
|
|
|
10
10
|
* Проверяет наличие `yarn.lock` в директории проекта. Используется как дефолт для `useYarn`.
|
|
11
11
|
*/
|
|
12
12
|
export declare function detectUseYarn(cwd: string): boolean;
|
|
13
|
+
type GetYarnBinSymlinkCommandParams = {
|
|
14
|
+
yarnVersion: YarnVersion;
|
|
15
|
+
cwd: string;
|
|
16
|
+
};
|
|
17
|
+
/**
|
|
18
|
+
* Читает значение yarnPath из .yarnrc.yml.
|
|
19
|
+
* Возвращает путь к бинарнику yarn (например .yarn/releases/yarn-4.18.0.cjs) или null.
|
|
20
|
+
*/
|
|
21
|
+
export declare function getYarnPathFromRc(cwd: string): string | null;
|
|
22
|
+
/**
|
|
23
|
+
* Возвращает команду для создания symlink на yarn бинарник в Docker-образе.
|
|
24
|
+
* Используется при yarn 2+ с yarnPath в .yarnrc.yml, чтобы yarn был доступен
|
|
25
|
+
* в PATH внутри Docker-образов (где yarn не установлен глобально).
|
|
26
|
+
* Возвращает пустую строку, если symlink не нужен.
|
|
27
|
+
*/
|
|
28
|
+
export declare function getYarnBinSymlinkCommand({ yarnVersion, cwd, }: GetYarnBinSymlinkCommandParams): string;
|
|
13
29
|
type GetPruningCommandParams = {
|
|
14
30
|
yarnVersion: YarnVersion;
|
|
15
31
|
clientOnly: boolean;
|
package/build/utils/yarn.js
CHANGED
|
@@ -18,6 +18,44 @@ export function getYarnVersion({ useYarn }) {
|
|
|
18
18
|
export function detectUseYarn(cwd) {
|
|
19
19
|
return fs.existsSync(path.join(cwd, 'yarn.lock'));
|
|
20
20
|
}
|
|
21
|
+
/**
|
|
22
|
+
* Читает значение yarnPath из .yarnrc.yml.
|
|
23
|
+
* Возвращает путь к бинарнику yarn (например .yarn/releases/yarn-4.18.0.cjs) или null.
|
|
24
|
+
*/
|
|
25
|
+
export function getYarnPathFromRc(cwd) {
|
|
26
|
+
const rcPath = path.join(cwd, '.yarnrc.yml');
|
|
27
|
+
if (!shell.test('-f', rcPath)) {
|
|
28
|
+
return null;
|
|
29
|
+
}
|
|
30
|
+
let content;
|
|
31
|
+
try {
|
|
32
|
+
content = fs.readFileSync(rcPath, 'utf8');
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
// Ищем строку вида: yarnPath: .yarn/releases/yarn-4.18.0.cjs
|
|
38
|
+
// Значение может быть в кавычках или без
|
|
39
|
+
const match = content.match(/^\s*yarnPath:\s*['"]?([^'"\s]+)['"]?\s*$/m);
|
|
40
|
+
return match ? match[1] : null;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Возвращает команду для создания symlink на yarn бинарник в Docker-образе.
|
|
44
|
+
* Используется при yarn 2+ с yarnPath в .yarnrc.yml, чтобы yarn был доступен
|
|
45
|
+
* в PATH внутри Docker-образов (где yarn не установлен глобально).
|
|
46
|
+
* Возвращает пустую строку, если symlink не нужен.
|
|
47
|
+
*/
|
|
48
|
+
export function getYarnBinSymlinkCommand({ yarnVersion, cwd, }) {
|
|
49
|
+
if (yarnVersion !== '2+') {
|
|
50
|
+
return '';
|
|
51
|
+
}
|
|
52
|
+
const yarnPath = getYarnPathFromRc(cwd);
|
|
53
|
+
if (!yarnPath) {
|
|
54
|
+
return '';
|
|
55
|
+
}
|
|
56
|
+
// WORKDIR в Dockerfile = /src
|
|
57
|
+
return `ln -sf /src/${yarnPath} /usr/local/bin/yarn && \\\n `;
|
|
58
|
+
}
|
|
21
59
|
/**
|
|
22
60
|
* Команда удаления dev-зависимостей перед копированием проекта в образ.
|
|
23
61
|
*/
|
package/docs/api.md
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
Программное API
|
|
2
|
+
===
|
|
3
|
+
|
|
4
|
+
Пакет устроен как набор чистых функций: конфиг → строка. Никакого глобального состояния — всё, что
|
|
5
|
+
влияет на результат, приходит явным объектом опций. Поэтому любую часть сборки можно вызвать из
|
|
6
|
+
своего скрипта.
|
|
7
|
+
|
|
8
|
+
## buildArtifact
|
|
9
|
+
|
|
10
|
+
Тот же пайплайн, что и у CLI: диспетчеризует на `buildDockerImage`/`buildArchive` по полю `artifact`.
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
import { buildArtifact } from '@alfalab/arui-scripts-artifacts';
|
|
14
|
+
|
|
15
|
+
await buildArtifact({
|
|
16
|
+
name: 'my-app',
|
|
17
|
+
version: '1.0.0',
|
|
18
|
+
docker: {
|
|
19
|
+
variant: 'compiled',
|
|
20
|
+
registry: 'registry.example.com',
|
|
21
|
+
buildArgs: { COMMIT_SHA: process.env.COMMIT_SHA ?? '' },
|
|
22
|
+
},
|
|
23
|
+
});
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Принимает все [настройки](settings.md) плюс два поля, которых нет в конфиге:
|
|
27
|
+
|
|
28
|
+
- `argv` — аргументы вида `name=... version=... registry=...`, накладываются поверх опций;
|
|
29
|
+
- `beforeBuild` — хук `(config) => void | Promise<void>`, вызывается после очистки `buildPath`, но до
|
|
30
|
+
`build.command`. Если приложение собирается хуком, выставьте `build.command: null`.
|
|
31
|
+
|
|
32
|
+
`buildDockerImage` и `buildArchive` доступны напрямую, если тип артефакта известен заранее.
|
|
33
|
+
|
|
34
|
+
## Пошаговая сборка
|
|
35
|
+
|
|
36
|
+
Если нужен контроль над каждым шагом — те же чистые функции по отдельности:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
import {
|
|
40
|
+
exec,
|
|
41
|
+
getBuildParams,
|
|
42
|
+
getDockerBuildCommand,
|
|
43
|
+
prepareFilesForDocker,
|
|
44
|
+
renderTemplates,
|
|
45
|
+
resolveArtifactsConfig,
|
|
46
|
+
} from '@alfalab/arui-scripts-artifacts';
|
|
47
|
+
|
|
48
|
+
const config = resolveArtifactsConfig({
|
|
49
|
+
serverOutput: 'server/index.js',
|
|
50
|
+
docker: { variant: 'compiled' },
|
|
51
|
+
});
|
|
52
|
+
const templates = renderTemplates({ config });
|
|
53
|
+
|
|
54
|
+
const { restoreDockerIgnore } = await prepareFilesForDocker({ config, templates });
|
|
55
|
+
|
|
56
|
+
await exec(getDockerBuildCommand(config));
|
|
57
|
+
await restoreDockerIgnore();
|
|
58
|
+
await exec(`docker push ${getBuildParams(config).imageFullName}`);
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
| Функция | Что делает |
|
|
62
|
+
| ------------------------ | --------------------------------------------------------------------------------- |
|
|
63
|
+
| `resolveArtifactsConfig` | донасыщает частичные опции дефолтами, возвращает `ResolvedArtifactsConfig` |
|
|
64
|
+
| `renderTemplates` | рендерит все файлы артефакта с учетом `templates`/`overrides` |
|
|
65
|
+
| `prepareFilesForDocker` | готовит временную директорию и `.dockerignore`, возвращает `restoreDockerIgnore` |
|
|
66
|
+
| `getBuildParams` | полное имя образа и пути (`getBuildParamsFromArgs` — с учетом аргументов CLI) |
|
|
67
|
+
| `getDockerBuildCommand` | строка команды `docker build` |
|
|
68
|
+
| `runHostPipeline` | очистка `buildPath`, сборка приложения, удаление dev-зависимостей |
|
|
69
|
+
| `exec` | запуск команды с прокинутым stdio; кидает `ExecError` с кодом возврата |
|
|
70
|
+
|
|
71
|
+
Рендереры отдельных файлов (`renderDockerfile`, `renderDockerfileCompiled`, `renderNginxConf`,
|
|
72
|
+
`renderBaseNginxConf`, `renderStartScript`) тоже экспортируются — см.
|
|
73
|
+
[Кастомизацию файлов артефакта](templates.md).
|
|
74
|
+
|
|
75
|
+
## Работа с конфигом
|
|
76
|
+
|
|
77
|
+
Разбор конфига доступен отдельно — так CLI можно встроить в свой:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import {
|
|
81
|
+
extractConfigPath,
|
|
82
|
+
resolveCommandOptions,
|
|
83
|
+
resolveConfigFile,
|
|
84
|
+
} from '@alfalab/arui-scripts-artifacts';
|
|
85
|
+
|
|
86
|
+
const argv = process.argv.slice(2);
|
|
87
|
+
const configFile = await resolveConfigFile(process.cwd(), extractConfigPath(argv));
|
|
88
|
+
const options = resolveCommandOptions('docker-build:server', configFile);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
| Функция | Что делает |
|
|
92
|
+
| ----------------------- | ----------------------------------------------------------------------------------- |
|
|
93
|
+
| `resolveConfigFile` | находит и загружает конфиг проекта (TS/ESM/CJS); если конфига нет — `{}` |
|
|
94
|
+
| `findConfigFile` / `loadConfigFile` | те же шаги по отдельности |
|
|
95
|
+
| `extractConfigPath` | достает `--config`/`-c`/`--c` из аргументов до построения CLI |
|
|
96
|
+
| `resolveCommandOptions` | опции конкретной команды: встроенные дефолты → верхний уровень → `commands[имя]` |
|
|
97
|
+
| `getAvailableCommands` | список доступных команд — встроенные плюс объявленные в конфиге |
|
|
98
|
+
| `mergeConfigFiles` | сливает несколько конфигов по тем же правилам (секции по полям, `commands` по имени) |
|
|
99
|
+
| `createCli` | собирает commander-CLI по конфигу — по подкоманде на каждую доступную сборку |
|
|
100
|
+
| `defineConfig` | хелпер типизации конфига, в рантайме ничего не делает |
|
|
101
|
+
|
|
102
|
+
`mergeConfigFiles` нужен тем, кто отдает CLI собственный конфиг (`-c`) и хочет доложить поверх
|
|
103
|
+
пользовательский — так делает `arui-scripts`, чтобы `arui-scripts-artifacts.ts` в корне проекта
|
|
104
|
+
продолжал работать вместе с настройками из конфига arui-scripts.
|
|
105
|
+
|
|
106
|
+
## Утилиты
|
|
107
|
+
|
|
108
|
+
- `getYarnVersion`, `detectUseYarn`, `getInstallProductionCommand`, `getPruningCommand`,
|
|
109
|
+
`getYarnPathFromRc`, `getYarnBinSymlinkCommand` — определение менеджера зависимостей и команды,
|
|
110
|
+
которые из него следуют;
|
|
111
|
+
- `dockerVersionSatisfies`, `getPlatformFlag` — проверка версии docker и вычисление `--platform`;
|
|
112
|
+
- `shellQuote` — экранирование значения для shell-команды;
|
|
113
|
+
- константы имен файлов и дефолтов: `DOCKERFILE_FILENAME`, `DOCKERIGNORE_FILENAME`,
|
|
114
|
+
`NGINX_CONFIG_FILENAME`, `BASE_NGINX_CONFIG_FILENAME`, `START_SCRIPT_FILENAME`,
|
|
115
|
+
`ENV_CONFIG_FILENAME`, `DEFAULT_BASE_DOCKER_IMAGE`, `DELETE_NPM_COMMAND` и соседние.
|
|
116
|
+
|
|
117
|
+
Типы (`ArtifactsOptions`, `ResolvedArtifactsConfig`, `ArtifactsConfigFile`, `ArtifactTemplates`,
|
|
118
|
+
`ArtifactTemplateOverrides`, `TemplateKey` и остальные) экспортируются из корня пакета.
|
package/docs/cli.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
CLI
|
|
2
|
+
===
|
|
3
|
+
|
|
4
|
+
После установки пакета команды доступны через `arui-scripts-artifacts <команда>`:
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
arui-scripts-artifacts <команда> [--config <путь до конфига>] [name=... version=... registry=...]
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Обычно команды прописывают в `package.json`:
|
|
11
|
+
|
|
12
|
+
```json
|
|
13
|
+
{
|
|
14
|
+
"scripts": {
|
|
15
|
+
"docker-build": "arui-scripts-artifacts docker-build",
|
|
16
|
+
"docker-build:compiled": "arui-scripts-artifacts docker-build:compiled",
|
|
17
|
+
"archive-build": "arui-scripts-artifacts archive-build"
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Глобальные флаги
|
|
23
|
+
|
|
24
|
+
- `arui-scripts-artifacts --help` — список доступных команд: встроенных и объявленных в конфиге
|
|
25
|
+
проекта.
|
|
26
|
+
- `arui-scripts-artifacts --version` (`-v`) — версия пакета.
|
|
27
|
+
- `arui-scripts-artifacts <команда> --help` — справка по конкретной команде.
|
|
28
|
+
- `--config <путь>` (`-c`, а также `--c`) — путь до конфига, см. ниже.
|
|
29
|
+
|
|
30
|
+
Запуск без команды печатает список доступных.
|
|
31
|
+
|
|
32
|
+
## Позиционные аргументы
|
|
33
|
+
|
|
34
|
+
Имя образа формируется как `{docker.registry}/{name}:{version}`. `name` и `version` по умолчанию
|
|
35
|
+
берутся из `package.json`, но их можно переопределить прямо в команде — это удобно в CI:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
arui-scripts-artifacts docker-build name=container-name version=0.1-beta
|
|
39
|
+
arui-scripts-artifacts docker-build registry=registry.example.com version=$CI_COMMIT_TAG
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Поддерживаются `name=`, `version=` и `registry=`; они имеют наивысший приоритет — перекрывают и
|
|
43
|
+
конфиг, и секцию команды. Неизвестные аргументы игнорируются с предупреждением.
|
|
44
|
+
|
|
45
|
+
## Конфиг
|
|
46
|
+
|
|
47
|
+
Конфиг ищется в корне проекта по первому совпадению из списка:
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
arui-scripts-artifacts.ts
|
|
51
|
+
arui-scripts-artifacts.mts
|
|
52
|
+
arui-scripts-artifacts.cts
|
|
53
|
+
arui-scripts-artifacts.js
|
|
54
|
+
arui-scripts-artifacts.mjs
|
|
55
|
+
arui-scripts-artifacts.cjs
|
|
56
|
+
arui-scripts-artifacts.config.ts
|
|
57
|
+
arui-scripts-artifacts.config.js
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Путь можно задать явно — `--c`, `--config` или `-c`, со знаком равенства или отдельным аргументом:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
arui-scripts-artifacts docker-build --c './configs/docker.prod.ts'
|
|
64
|
+
arui-scripts-artifacts docker-build --config=./configs/docker.prod.ts version=1.2.3
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Явно заданный путь обязан существовать: молча проигнорировать опечатку в `--config` хуже, чем упасть.
|
|
68
|
+
Если конфига нет вовсе — сборка идет на дефолтах.
|
|
69
|
+
|
|
70
|
+
Конфиг может быть на TypeScript, ESM или CommonJS — загрузчик (jiti) разбирается сам, регистрировать
|
|
71
|
+
`ts-node`/`tsx` в проекте не нужно. Экспортировать можно объект или (в том числе асинхронную)
|
|
72
|
+
функцию, возвращающую объект:
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { defineConfig } from '@alfalab/arui-scripts-artifacts';
|
|
76
|
+
|
|
77
|
+
export default defineConfig(async () => ({
|
|
78
|
+
docker: { registry: await resolveRegistry() },
|
|
79
|
+
}));
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`defineConfig` ничего не делает в рантайме — он нужен только ради автодополнения и проверки типов.
|
|
83
|
+
|
|
84
|
+
Полный список настроек — в [Настройках](settings.md), список команд — в [Командах](commands.md).
|
|
85
|
+
|
|
86
|
+
## Локальные файлы проекта
|
|
87
|
+
|
|
88
|
+
CLI сам подхватывает лежащие в корне проекта `Dockerfile`, `start.sh`, `nginx.conf` и
|
|
89
|
+
`base-nginx.conf` — если они есть, они заменяют сгенерированные шаблоны. Явно заданная секция
|
|
90
|
+
[`localFiles`](settings.md#localfiles) имеет приоритет над автодетектом, а `docker-build:compiled`
|
|
91
|
+
подмену `Dockerfile` и `start.sh` запрещает — как и в `arui-scripts`.
|
|
92
|
+
|
|
93
|
+
## Встраивание в свой CLI
|
|
94
|
+
|
|
95
|
+
Разбор конфига и сборка доступны как обычные функции, поэтому команду можно завернуть в собственный
|
|
96
|
+
скрипт или CLI — см. [Программное API](api.md).
|
package/docs/commands.md
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
Команды
|
|
2
|
+
===
|
|
3
|
+
|
|
4
|
+
Команда — это именованный набор опций сборки. Встроенных команд три, остальные объявляются в секции
|
|
5
|
+
`commands` конфига: **кастомные сборочные скрипты в проекте не нужны**.
|
|
6
|
+
|
|
7
|
+
## Встроенные команды
|
|
8
|
+
|
|
9
|
+
| Команда | Что делает |
|
|
10
|
+
| ----------------------- | ------------------------------------------------------------------------------------- |
|
|
11
|
+
| `docker-build` | приложение собирается на хосте (`npm run build`), результат кладется в образ |
|
|
12
|
+
| `docker-build:compiled` | зависимости и сборка выполняются внутри образа, слои кешируются |
|
|
13
|
+
| `archive-build` | tar-архив с production-сборкой: `buildPath`, `node_modules`, `package.json`, `config` |
|
|
14
|
+
|
|
15
|
+
Встроенная команда задает только то, чем отличается от остальных, — все прочее берется из конфига
|
|
16
|
+
проекта:
|
|
17
|
+
|
|
18
|
+
| Команда | Задает |
|
|
19
|
+
| ----------------------- | ------------------------------------------------------------------------------------------ |
|
|
20
|
+
| `docker-build` | `artifact: 'docker'`, `docker.variant: 'runtime'`, `docker.addNodeModulesToDockerIgnore: false`, подмена `Dockerfile`/`start.sh` разрешена |
|
|
21
|
+
| `docker-build:compiled` | `artifact: 'docker'`, `docker.variant: 'compiled'`, `docker.addNodeModulesToDockerIgnore: true`, подмена `Dockerfile`/`start.sh` запрещена |
|
|
22
|
+
| `archive-build` | `artifact: 'archive'` |
|
|
23
|
+
|
|
24
|
+
Что из этого следует для остальных настроек (`build.command`, `build.cleanBuildPath` и прочих) —
|
|
25
|
+
в [пайплайне сборки](pipeline.md).
|
|
26
|
+
|
|
27
|
+
Встроенные команды можно донасыщать и переопределять — достаточно объявить команду с тем же именем
|
|
28
|
+
в `commands`.
|
|
29
|
+
|
|
30
|
+
## Свои команды
|
|
31
|
+
|
|
32
|
+
Команда наследует верхний уровень конфига, поэтому в ней описывается только то, чем она отличается:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { defineConfig } from '@alfalab/arui-scripts-artifacts';
|
|
36
|
+
|
|
37
|
+
export default defineConfig({
|
|
38
|
+
docker: { baseImage: 'registry.example.com/base:2.0.0' },
|
|
39
|
+
nginx: { baseConf: { workerProcesses: 4 } },
|
|
40
|
+
|
|
41
|
+
commands: {
|
|
42
|
+
// серверный образ: свой энтрипоинт и порт, всё остальное — из верхнего уровня
|
|
43
|
+
'docker-build:server': {
|
|
44
|
+
docker: { variant: 'compiled' },
|
|
45
|
+
serverOutput: 'server/index.js',
|
|
46
|
+
// сольется с верхнеуровневой секцией nginx
|
|
47
|
+
nginx: { port: 9090, baseConf: { workerConnections: 100 } },
|
|
48
|
+
},
|
|
49
|
+
|
|
50
|
+
// образ только со статикой
|
|
51
|
+
'docker-build:static': {
|
|
52
|
+
clientOnly: true,
|
|
53
|
+
build: { command: 'npm run build:static' },
|
|
54
|
+
},
|
|
55
|
+
|
|
56
|
+
// еще один архив — с отдельным именем и своей сборкой
|
|
57
|
+
'archive-build:e2e': {
|
|
58
|
+
artifact: 'archive',
|
|
59
|
+
archive: { name: 'e2e.tar' },
|
|
60
|
+
build: { command: 'npm run build:e2e' },
|
|
61
|
+
},
|
|
62
|
+
},
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
arui-scripts-artifacts docker-build:server
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Объявленные команды попадают в `--help` наравне со встроенными, а опечатка в имени дает подсказку.
|
|
71
|
+
|
|
72
|
+
## Как складываются настройки
|
|
73
|
+
|
|
74
|
+
Приоритет по возрастанию:
|
|
75
|
+
|
|
76
|
+
1. дефолты встроенной команды (если команда встроенная);
|
|
77
|
+
2. верхний уровень конфига;
|
|
78
|
+
3. секция `commands[<имя команды>]`;
|
|
79
|
+
4. [позиционные аргументы CLI](cli.md#позиционные-аргументы) `name=`, `version=`, `registry=`.
|
|
80
|
+
|
|
81
|
+
Секции (`docker`, `nginx`, `archive`, `build`, `packageManager`, `localFiles`, `templates`,
|
|
82
|
+
`overrides`) сливаются по полям, скалярные опции заменяются целиком. Вложенный `nginx.baseConf`
|
|
83
|
+
тоже сливается по полям, но `baseConf: false`/`null` — это осмысленное «не генерировать базовый
|
|
84
|
+
конфиг», такое значение заменяет секцию целиком.
|
|
85
|
+
|
|
86
|
+
То же слияние доступно и снаружи — `mergeConfigFiles`, см. [Программное API](api.md). Именно так
|
|
87
|
+
`arui-scripts` кладет `arui-scripts-artifacts.ts` проекта поверх своих настроек.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
Миграция с `arui-scripts docker-build`
|
|
2
|
+
===
|
|
3
|
+
|
|
4
|
+
Поведение и шаблоны совпадают — отрендеренные Dockerfile, nginx-конфиги и `start.sh` те же самые.
|
|
5
|
+
Отличаются имена и расположение настроек: вместо плоского конфига `arui-scripts` они разложены по
|
|
6
|
+
секциям в `arui-scripts-artifacts.ts`.
|
|
7
|
+
|
|
8
|
+
Настройки сборки артефактов в конфиге `arui-scripts` продолжают работать, но объявлены устаревшими:
|
|
9
|
+
команды сборки печатают предупреждение со ссылкой на замену, а в следующей мажорной версии они будут
|
|
10
|
+
удалены.
|
|
11
|
+
|
|
12
|
+
## Таблица соответствия
|
|
13
|
+
|
|
14
|
+
| arui-scripts | @alfalab/arui-scripts-artifacts |
|
|
15
|
+
| ------------------------------------------------------------ | -------------------------------------- |
|
|
16
|
+
| `configs.dockerRegistry` | `docker.registry` |
|
|
17
|
+
| `configs.baseDockerImage` | `docker.baseImage` |
|
|
18
|
+
| `configs.runFromNonRootUser` | `docker.runFromNonRootUser` |
|
|
19
|
+
| `configs.deleteNpm` | `docker.deleteNpm` |
|
|
20
|
+
| `configs.clientServerPort` | `nginx.port` |
|
|
21
|
+
| `configs.nginxRootPath` | `nginx.rootPath` |
|
|
22
|
+
| `configs.nginx` (настройки базового конфига) | `nginx.baseConf` |
|
|
23
|
+
| `configs.dictionaryCompression.enablePreviousVersionHeaders` | `nginx.enablePreviousVersionHeaders` |
|
|
24
|
+
| `configs.archiveName` | `archive.name` |
|
|
25
|
+
| `configs.additionalBuildPath` | `archive.additionalPaths` |
|
|
26
|
+
| `configs.removeDevDependenciesDuringDockerBuild` | `build.removeDevDependencies` |
|
|
27
|
+
| `configs.useYarn` | `packageManager.useYarn` |
|
|
28
|
+
| `configs.localDockerfile` и соседние | `localFiles.dockerfile` и соседние |
|
|
29
|
+
| оверрайд `Dockerfile` | `overrides.dockerfile` |
|
|
30
|
+
| оверрайд `DockerfileCompiled` | `overrides.dockerfileCompiled` |
|
|
31
|
+
| оверрайд `nginx` (server-блок) | `overrides.nginxConf` |
|
|
32
|
+
| оверрайд `nginxConf` (базовый http-блок) | `overrides.baseNginxConf` |
|
|
33
|
+
| оверрайд `start.sh` | `overrides.startScript` |
|
|
34
|
+
|
|
35
|
+
⚠️ В `arui-scripts` имена `nginx` и `nginxConf` исторически перепутаны: `nginx` — это server-блок, а
|
|
36
|
+
`nginxConf` — базовый конфиг. Здесь они названы по смыслу, поэтому **`nginxConf` в двух пакетах
|
|
37
|
+
означает разные файлы**. Переносить оверрайды по таблице выше, а не по совпадению имен.
|
|
38
|
+
|
|
39
|
+
## Как выглядит перенос
|
|
40
|
+
|
|
41
|
+
Было, в `package.json` или конфиге `arui-scripts`:
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"aruiScripts": {
|
|
46
|
+
"dockerRegistry": "registry.example.com",
|
|
47
|
+
"baseDockerImage": "alfabankui/arui-scripts:24.10.0-slim",
|
|
48
|
+
"nginx": { "workerProcesses": 4 },
|
|
49
|
+
"archiveName": "e2e.tar"
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Стало, в `arui-scripts-artifacts.ts`:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import { defineConfig } from '@alfalab/arui-scripts-artifacts';
|
|
58
|
+
|
|
59
|
+
export default defineConfig({
|
|
60
|
+
docker: {
|
|
61
|
+
registry: 'registry.example.com',
|
|
62
|
+
baseImage: 'alfabankui/arui-scripts:24.10.0-slim',
|
|
63
|
+
},
|
|
64
|
+
nginx: { baseConf: { workerProcesses: 4 } },
|
|
65
|
+
archive: { name: 'e2e.tar' },
|
|
66
|
+
});
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Оверрайды из `arui-scripts.overrides.ts` переезжают в секции
|
|
70
|
+
[`templates`/`overrides`](templates.md) того же файла.
|
|
71
|
+
|
|
72
|
+
Конфиг можно завести, не переключая команды: `arui-scripts docker-build` находит
|
|
73
|
+
`arui-scripts-artifacts.ts` по обычным правилам и кладет его поверх настроек из конфига
|
|
74
|
+
`arui-scripts`. Заводить его по-прежнему не обязательно.
|
|
75
|
+
|
|
76
|
+
## publicPath
|
|
77
|
+
|
|
78
|
+
`publicPath` по умолчанию — `` `${assetsPath}/` `` (то есть `assets/`), как это считает
|
|
79
|
+
`arui-scripts`. Пустой `publicPath` дал бы в nginx-конфиге второй `location /`, и nginx не поднялся
|
|
80
|
+
бы с `duplicate location "/"`.
|
|
81
|
+
|
|
82
|
+
## Отличие в `archive-build`
|
|
83
|
+
|
|
84
|
+
Старый `arui-scripts archive-build` подхватывал локальный `nginx.conf`, но игнорировал локальный
|
|
85
|
+
`start.sh`. Здесь локальные файлы обрабатываются единообразно: `start.sh` из корня проекта тоже
|
|
86
|
+
используется. Отключается через `localFiles.allowStartScript: false`.
|
package/docs/pipeline.md
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
Пайплайн сборки
|
|
2
|
+
===
|
|
3
|
+
|
|
4
|
+
Хост-пайплайн общий для docker-образа и tar-архива, поэтому оба собираются из одного и того же
|
|
5
|
+
состояния проекта. Какие шаги выполнятся — зависит от типа артефакта, варианта и опций секции
|
|
6
|
+
[`build`](settings.md#build).
|
|
7
|
+
|
|
8
|
+
| Шаг | Опция | Дефолт `runtime` | Дефолт `compiled` |
|
|
9
|
+
| ------------------------- | ------------------------------------------------------------- | ----------------- | ----------------- |
|
|
10
|
+
| очистка `buildPath` | `build.cleanBuildPath` | `true` | `false` |
|
|
11
|
+
| хук перед сборкой | `beforeBuild` | — | — |
|
|
12
|
+
| сборка приложения | `build.command` | `'npm run build'` | `null` |
|
|
13
|
+
| удаление dev-зависимостей | `build.removeDevDependencies` / `packageManager.pruneCommand` | `true` | `false` |
|
|
14
|
+
| `docker build` / `tar` | — | всегда | всегда |
|
|
15
|
+
| `docker push` | `docker.push` | `!debug` | `!debug` |
|
|
16
|
+
|
|
17
|
+
Для `artifact: 'archive'` хост-пайплайн включен всегда (внутри tar-а собирать нечего), поэтому
|
|
18
|
+
`docker.variant` на него не влияет.
|
|
19
|
+
|
|
20
|
+
`beforeBuild` — хук программного API (см. [Программное API](api.md)), а не настройка конфига. Он
|
|
21
|
+
вызывается после очистки `buildPath`, но до `build.command`: если приложение собирается хуком,
|
|
22
|
+
выставьте `build.command: null`.
|
|
23
|
+
|
|
24
|
+
## docker-образ
|
|
25
|
+
|
|
26
|
+
1. Рендерятся шаблоны — с учетом [`templates` и `overrides`](templates.md).
|
|
27
|
+
2. Создается временная директория [`docker.tempDirName`](settings.md#dockertempdirname) (по умолчанию
|
|
28
|
+
`.docker-build`), в нее кладутся `Dockerfile`, `nginx.conf`, при включенном `nginx.baseConf` —
|
|
29
|
+
`base-nginx.conf`, и `start.sh` (с правами `0555`). [Локальные файлы](templates.md#локальные-файлы)
|
|
30
|
+
проекта, если разрешены, побеждают сгенерированные.
|
|
31
|
+
3. При `docker.addNodeModulesToDockerIgnore` в `.dockerignore` дописывается `node_modules` — на время
|
|
32
|
+
сборки; после нее файл возвращается в исходное состояние (а если его не было — удаляется).
|
|
33
|
+
4. Прогоняется хост-пайплайн из таблицы выше.
|
|
34
|
+
5. Запускается `docker build` с флагом [`--platform`](settings.md#dockerplatform),
|
|
35
|
+
`--build-arg` для путей до сгенерированных файлов и с
|
|
36
|
+
[`docker.buildArgs`](settings.md#dockerbuildargs).
|
|
37
|
+
6. Временная директория удаляется, `.dockerignore` восстанавливается, и при `docker.push`
|
|
38
|
+
выполняется `docker push`.
|
|
39
|
+
|
|
40
|
+
При ошибке на любом шаге временная директория и `.dockerignore` тоже приводятся в порядок, а сама
|
|
41
|
+
ошибка пробрасывается наружу; стек печатается только в режиме [`debug`](settings.md#debug).
|
|
42
|
+
|
|
43
|
+
### Варианты образа
|
|
44
|
+
|
|
45
|
+
- **`runtime`** — приложение собирается на хосте, в образ кладется результат сборки. Быстрее на
|
|
46
|
+
машине разработчика, не требует зависимостей внутри образа.
|
|
47
|
+
- **`compiled`** — в образ копируются `package.json`, лок-файл и (для yarn 2+) `.yarnrc.yml` с
|
|
48
|
+
`.yarn`, внутри ставятся production-зависимости, и только потом добавляется остальной проект. Слой
|
|
49
|
+
с зависимостями кешируется между сборками, поэтому вариант выгоден в CI/CD.
|
|
50
|
+
|
|
51
|
+
## tar-архив
|
|
52
|
+
|
|
53
|
+
1. Рендерятся шаблоны, создается временная директория
|
|
54
|
+
[`archive.tempDirName`](settings.md#archivetempdirname) (по умолчанию `.archive-build`), в нее
|
|
55
|
+
кладутся `nginx.conf` и `start.sh`.
|
|
56
|
+
2. Прогоняется тот же хост-пайплайн.
|
|
57
|
+
3. В директорию копируются `buildPath`, `node_modules`, `package.json` и
|
|
58
|
+
[`archive.additionalPaths`](settings.md#archiveadditionalpaths) (по умолчанию `config`).
|
|
59
|
+
4. Содержимое пакуется в [`archive.name`](settings.md#archivename) (по умолчанию `build.tar`),
|
|
60
|
+
временная директория удаляется.
|
|
61
|
+
|
|
62
|
+
Dockerfile для архива не рендерится, а `docker`-секция не используется.
|