Permalink
Show file tree
Hide file tree
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
feat(docs): updated usage/build/stapel section (lang:en+ru)
Signed-off-by: Timofey Kirillov <timofey.kirillov@flant.com>
- Loading branch information
1 parent
3af476a
commit 0c504a4
Showing
19 changed files
with
3,348 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| --- | ||
| title: Base image | ||
| permalink: usage/build_draft/stapel/base.html | ||
| author: Alexey Igrychev <alexey.igrychev@flant.com> | ||
| directive_summary: base_image | ||
| --- | ||
|
|
||
| Here's a minimal `werf.yaml`. It describes a _image_ named `example` that is based on a _base image_ named `alpine`: | ||
|
|
||
| ```yaml | ||
| project: my-project | ||
| configVersion: 1 | ||
| --- | ||
| image: example | ||
| from: alpine | ||
| ``` | ||
|
|
||
| _Base image_ can be declared with `from`, `fromImage` or `fromArtifact` directive. | ||
|
|
||
| ## from, fromLatest | ||
|
|
||
| The `from` directive defines the name and tag of a _base image_. If absent, tag defaults to `latest`. | ||
|
|
||
| ```yaml | ||
| from: <image>[:<tag>] | ||
| ``` | ||
|
|
||
| By default, the assembly process does not depend on actual _base image_ digest in the repository, only on _from_ directive value. | ||
| Thus, changing _base image_ locally or in the repository does not matter if _from_ stage is already exists in _storage_. | ||
|
|
||
| If you want always build the image with actual _base image_ you should use _fromLatest_ directive. | ||
| _fromLatest_ directive allows connecting the assembly process with the _base image_ digest getting from the repository. | ||
|
|
||
| ```yaml | ||
| fromLatest: true | ||
| ``` | ||
|
|
||
| > By default, the use of the `fromLatest` directive is not allowed by giterminism (read more about it [here]({{ "usage/project_configuration/giterminism.html" | true_relative_url }})) | ||
| ## fromImage and fromArtifact | ||
|
|
||
| Besides using docker image from a repository, the _base image_ can refer to _image_ or [_artifact_]({{ "usage/build_draft/stapel/imports.html#what-is-an-artifact" | true_relative_url }}), that is described in the same `werf.yaml`. | ||
|
|
||
| ```yaml | ||
| fromImage: <image name> | ||
| fromArtifact: <artifact name> | ||
| ``` | ||
|
|
||
| If a _base image_ is specific to a particular application, | ||
| it is reasonable to store its description with _images_ and _artifacts_ which are used it as opposed to storing the _base image_ in a container registry. | ||
|
|
||
| Also, this method can be useful if the stages of _stage conveyor_ are not enough for building the image. You can design your _stage conveyor_. | ||
|
|
||
| <a class="google-drawings" href="{{ "images/configuration/base_image2.png" | true_relative_url }}" data-featherlight="image"> | ||
| <img src="{{ "images/configuration/base_image2_preview.png" | true_relative_url }}" alt="Conveyor with fromImage and fromArtifact stages"> | ||
| </a> | ||
|
|
||
| ## fromCacheVersion | ||
|
|
||
| The `fromCacheVersion` directive allows managing image reassembly. | ||
|
|
||
| ```yaml | ||
| fromCacheVersion: <arbitrary string> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| --- | ||
| title: Adding docker instructions | ||
| permalink: usage/build_draft/stapel/dockerfile.html | ||
| author: Alexey Igrychev <alexey.igrychev@flant.com> | ||
| directive_summary: docker | ||
| --- | ||
|
|
||
| [Dockerfile instructions](https://docs.docker.com/engine/reference/builder/) can be divided into two groups: build-time instructions and other instructions that effect on an image manifest. Build-time instructions do not make sense in a werf build process. Therefore, werf supports only following instructions: | ||
|
|
||
| * `USER` to set the user name (or UID) and optionally the user group (or GID) (read more [here](https://docs.docker.com/engine/reference/builder/#user)). | ||
| * `WORKDIR` to set the working directory (read more [here](https://docs.docker.com/engine/reference/builder/#workdir)). | ||
| * `VOLUME` to add mount point (read more [here](https://docs.docker.com/engine/reference/builder/#volume)). | ||
| * `ENV` to set the environment variable (read more [here](https://docs.docker.com/engine/reference/builder/#env)). | ||
| * `LABEL` to add metadata to an image (read more [here](https://docs.docker.com/engine/reference/builder/#label)). | ||
| * `EXPOSE` to inform Docker that the container listens on the specified network ports at runtime (read more [here](https://docs.docker.com/engine/reference/builder/#expose)) | ||
| * `ENTRYPOINT` to configure a container that will run as an executable (read more [here](https://docs.docker.com/engine/reference/builder/#entrypoint)). How stapel builder processes CMD and ENTRYPOINT is covered [here]({{ "/usage/build/build_process.html#how-the-stapel-builder-processes-cmd-and-entrypoint" | true_relative_url }}). | ||
| * `CMD` to provide default arguments for the `ENTRYPOINT` to configure a container that will run as an executable (read more [here](https://docs.docker.com/engine/reference/builder/#cmd)). How stapel builder processes CMD and ENTRYPOINT is covered [here]({{ "/usage/build/build_process.html#how-the-stapel-builder-processes-cmd-and-entrypoint" | true_relative_url }}). | ||
| * `HEALTHCHECK` to tell Docker how to test a container to check that it is still working (read more [here](https://docs.docker.com/engine/reference/builder/#healthcheck)) | ||
|
|
||
| These instructions can be specified in the `docker` config directive. | ||
|
|
||
| Here is an example of using docker instructions: | ||
|
|
||
| ```yaml | ||
| docker: | ||
| WORKDIR: /app | ||
| CMD: ["python", "./index.py"] | ||
| EXPOSE: '5000' | ||
| ENV: | ||
| TERM: xterm | ||
| LC_ALL: en_US.UTF-8 | ||
| ``` | ||
|
|
||
| Defined docker instructions are applied on the last stage called `docker_instructions`. | ||
| Thus, instructions do not affect other stages, ones just will be applied to a built image. | ||
|
|
||
| If need to use special environment variables in build-time of your application image, such as `TERM` environment, you should use a [base image]({{ "usage/build_draft/stapel/base.html" | true_relative_url }}) with these variables. | ||
|
|
||
| > Tip: you can also implement exporting environment variables right in [_user stage_]({{ "usage/build/building_images_with_stapel/assembly_instructions.html#what-are-user-stages" | true_relative_url }}) instructions |
Oops, something went wrong.