Проект содержит скрипты которые обеспечивают сборку контейнера docker и загрузку его в docker registry.  

Состав:
* build.sh - скрипт сборки образа
* import.sh - скрипт загрузки образа в docker registry
* .env - конфигурационный файл для запуска сборки в ручном режиме

#### Сборка контейнера
* Контейнер собирается с использованием Dockerfile либо файла, определяемого переменной `DOCKER_FILE`, из корня проекта. При этом в него передаются параметры:
  * Контекст сборки может быть определен переменной `DOCKER_BUILD_CONTEXT`, по умолчанию `.`
  * Для успешной сборки образа, контейнер, в котором происходит сборка (директива `image:` в `.gitlab-ci.yml` файле) должен иметь установленный bash и git.
    Для этих целей можно использовать образ `docker.ds.mlmsoft.cloud/images/docker`.
  * Имя базового образа, определяется переменной `DOCKER_BASEIMAGE` 
    (по умолчанию используется `ubuntu:18.04`)
  * Установка переменной `DOCKER_NO_PULL_BASEIMAGE` в непустое значение позволяет не осуществлять принудительный `docker pull` базового образа
  * Префикс собираемого локально образа задается переменной `DOCKER_IMAGE_PREFIX`  
    (по умолчанию `mlmsoft`)
  * Версия базового образа определяется (в порядке приоритета) либо переменной `VERSION`, либо содержимым файла `VERSION` из корня проекта, если файл отсутствует, берется версия `latest`
  * Maintainer контейнера определяется переменной `DOCKER_MAINTAINER` 
    (по умолчанию указывается email пользователя в gitlab или service@ds.mlmsoft.cloud при локальном запуске, если иное не указано в Dockerfile)
  * Имя собираемого образа оперделяется переменной `DOCKER_IMAGE_NAME`. По умолчанию используется короткое имя проекта в Gitlab (${CI_PROJECT_PATH#*/})
  * Тег собираемого образа определяется переменной `DOCKER_IMAGE_TAG`. При отсутствии переменной берется переменная `${VERSION}` и тд
  * Для передачи произвольных аргументов в Dockerfile можно использовать набор переменных DOCKER_ARG0...DOCKER_ARG9 (соблюдение нумерации не обязательно), в секции `before_script:` .gitlab-ci.yml:
  
    `export DOCKER_ARG1="VERSION=1.0.0"`
	
	Переменная VERSION будет доступна в Dockerfile через конструкцию `ARG VERSION`
	
	Альтернативно можно передевать аргументы в сборку как параметры сборочного скрипта в формате `ARG=value`.
	
* Контейнер выкладывается в docker registry `docker.ds.mlmsoft.cloud`, полный путь к контейнеру: 
 
    `docker.ds.mlmsoft.cloud/${CI_PROJECT_NAME}:${VERSION}` если имя образа совпадает с именем проекта, либо  
    `docker.ds.mlmsoft.cloud/${CI_PROJECT_NAME}/${IMAGE_NAME}:${VERSION}` если имя образа отлично от имени проекта
    
    где: 
    - `${CI_PROJECT_NAME}` полный путь проекта вида `<группа>/имя проекта>` или `<пользователь>/имя проекта>`  
    - `${VERSION}` это версия образа или `latest` в случае ее отсутствия.

#### Версионность образа
Правила формирования версии образа:
* Версия образа берется из файла VERSION, который должен располагаться в корне проекта
* В случае отсутствия файла, берется версия `:latest`

Правила определения версии базового образа (DOCKER_BASEIMAGE):
* Если в DOCKER_BASEIMAGE есть тег образа, в качестве DOCKER_BASEIMAGE берется значение переменной ${DOCKER_BASEIMAGE} без изменений
* Если в DOCKER_BASEIMAGE отсутствует тег образа, то берется ${DOCKER_BASEIMAGE}:${VERSION}

Правила определения версии итогового образа:
* Образ тегируется как ${IMAGE}:${VERSION}
* В случае импорта в регистри, образ тегируется как `docker.ds.mlmsoft.cloud/${CI_PROJECT_NAME}:${VERSION}`
* В случае, если сборка происходит не из ветки master, образ принудительно тегируется по имени ветки, из которой производится сборка.  
  Если происходит сборка не из ветки master и переменная `DOCKER_IMAGE_TAG` не пустая, то образ тегируется как `$DOCKER_IMAGE_TAG_$BRANCH`.  
  Даннове поведение можно отменить установив переменную `DOCKER_NO_BRANCH_TAG` в непустое значение.

Дополнительно возможно указать переменную `DOCKER_TAG_AS_LATEST`, которая отвечает за дополнительное тегирование образа тегом `latest` в регистри.

#### Подключение скриптов к проекту
Проект предполагает использование через механизм gitlab submodules или клонирование скриптов при сборке проекта. Примеры файлов и команды находятся в каталоге example/.  

##### Подключение через механизм git submodules
Доступно два варианта использования:  
 а) Использование фиксированной версии сборщика  
 б) Использование последней доступной версии  

Для настройки необходимо:
1) Однократно выполнить в проекте команду 
 
`git submodule add -b master ../../infra/ci-build-image.git ci/build-image`

2) В корне проекта разместить `Dockerfile` вида:
```
ARG DOCKER_BASEIMAGE
FROM ${DOCKER_BASEIMAGE}

ARG DOCKER_MAINTAINER
LABEL maintainer="${DOCKER_MAINTAINER}"

# Uncomment if you use assets/
#COPY assets/ /
```
3) а) Для использования фиксированной версии в `.gitlab-ci.yml` проекта прописать переменную `GIT_SUBMODULE_STRATEGY=recursive`  
   б) Для использования последней доступной версии в `.gitlab-ci.yml` проекта прописать переменную `GIT_SUBMODULE_STRATEGY=none`  

4) Осуществить вызов сборки в `.gitlab-ci.yml`:  
а) Вариант фиксированной версии: 
```
image: docker.ds.mlmsoft.cloud/images/docker

variables:
  DOCKER_BASEIMAGE: ubuntu:18.04
#  DOCKER_IMAGE_NAME: ${CI_PROJECT_PATH#*/}
#  DOCKER_IMAGE_TAG: latest 
  BUILD_SCRIPT: ci/build-image/build.sh
  GIT_SUBMODULE_STRATEGY: recursive

#before_script:
#  - export DOCKER_ARG0="key=value" 
#  - export DOCKER_ARG1="key=value"
  
stages:
  - build

build:
  stage: build
  script:
    - chmod +x "${BUILD_SCRIPT}" && "./${BUILD_SCRIPT}"
  when: manual
```

б) Вариант последней доступной версии:
```
image: docker.ds.mlmsoft.cloud/images/docker

variables:
  DOCKER_BASEIMAGE: ubuntu:18.04
#  DOCKER_IMAGE_NAME: ${CI_PROJECT_PATH#*/}
#  DOCKER_IMAGE_TAG: latest 
  BUILD_SCRIPT: ci/build-image/build.sh
  GIT_SUBMODULE_STRATEGY: none

#before_script:
#  - export DOCKER_ARG0="key=value" 
#  - export DOCKER_ARG1="key=value"
  
stages:
  - build

build:
  stage: build
  script:
    - git submodule sync
    - git submodule update --init --remote --force
    - chmod +x "${BUILD_SCRIPT}" && "./${BUILD_SCRIPT}"
  when: manual
```

5) Обновление submodule осуществляется командой:

`git submodule sync && git submodule update --init --remote`

##### Клонирование скриптов при сборке проекта

1) В корне проекта разместить `Dockerfile` вида:
```
ARG DOCKER_BASEIMAGE
FROM ${DOCKER_BASEIMAGE}

ARG DOCKER_MAINTAINER
LABEL maintainer="${DOCKER_MAINTAINER}"

# Uncomment if you use assets/
#COPY assets/ /
```

2) Осуществить вызов сборки в `.gitlab-ci.yml`:  
```
image: docker.ds.mlmsoft.cloud/images/docker

variables:
  DOCKER_BASEIMAGE: ubuntu:18.04
#  DOCKER_IMAGE_NAME: ${CI_PROJECT_PATH#*/}
#  DOCKER_IMAGE_TAG: latest 
  BUILD_SCRIPT: ci/build-image/build.sh

#before_script:
#  - export DOCKER_ARG0="key=value" 
#  - export DOCKER_ARG1="key=value"
  
stages:
  - build

build:
  stage: build
  script:
    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.ds.mlmsoft.cloud/infra/ci-build-image.git ${BUILD_SCRIPT%/*}
    - chmod +x "${BUILD_SCRIPT}" && "./${BUILD_SCRIPT}"
  when: manual
```


#### Ручной запуск
Возможен запуск сборки на локальной машине и выкладывание его в docker registry без внесения изменений в проект. Для этого рядом со сборочными скриптами в `/ci/build-images` должен находиться конфиг с именем `.env` (пример конфига см. в файле `sample.env`):
```
# Your project target image name and tag
DOCKER_IMAGE_NAME=image
DOCKER_IMAGE_TAG=latest

# Base image name and tag
DOCKER_BASEIMAGE=ubuntu:18.04

# Docker build context (leave it as is if not know that it is)
DOCKER_BUILD_CONTEXT=.
DOCKER_PROJECT=external/project
CI_COMMIT_REF_SLUG=master

# Registry credentials (need only if docker registry upload required)
REGISTRY_USER=%YOUR_GITLAB_USERNAME%
REGISTRY_PASSWORD=%YOUR_GITLAB_PASSWORD%
REGISTRY_URL=docker.ds.mlmsoft.cloud
```

Запуск сборки из каталога проекта: `./ci/build-image/build.sh`

При ручном запуске автоматическая загрузка в docker registry не происходит, необходимо использовать скрипт `import.sh`: 

`DOCKER_IMAGE=image ./import.sh`