Skip to content

Commit 30ee7f8

Browse files
LukasGenteleLukasGentele
committed
docs: finish image build and tag pages
1 parent ea11a7f commit 30ee7f8

7 files changed

Lines changed: 244 additions & 16 deletions

File tree

‎.vscode/settings.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@
55
"go.installDependenciesWhenBuilding": false,
66
"go.formatTool": "goimports",
77
"go.coverOnTestPackage": true,
8-
"go.useLanguageServer": true
8+
"go.useLanguageServer": true,
9+
"editor.tabSize": 2
910
}

‎docs/pages/configuration/images/build.mdx‎

Lines changed: 175 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
title: Build
2+
title: Image Building with DevSpace
33
sidebar_label: 1. Build
44
---
55

66
import ConfigPartialBuildConfig from '../_partials/v2beta1/images/group_buildConfig.mdx'
77
import ConfigPartialOverwrites from '../_partials/v2beta1/images/group_overwrites.mdx'
8+
import ConfigPartialRebuildStrategy from '../_partials/v2beta1/images/rebuildStrategy.mdx'
89
import PreventBuildTip from './_partials/prevent_build.mdx'
910

1011
DevSpace can build images using a variety of build engines.
@@ -38,33 +39,200 @@ The example above defines 3 images:
3839
- `api` with Dockerfile in `./Dockerfile` and build context in `./` (default values)
3940
- `payments` with Dockerfile in `./payments/Dockerfile` and build context in `./payments/`
4041
- `auth` with Dockerfile in `./auth/Dockerfile` and build context in `./auth/`
41-
Additionally, the image `auth` also defines a few [`buildArgs`](#buildArgs) and a [build `target`](#target-for-multi-stage-builds) for multi-stage builds.
42+
Additionally, the image `auth` also defines a few [`buildArgs`](#buildargs) and a [build `target`](#target-for-multi-stage-builds) for multi-stage builds.
4243

4344

44-
### 2. Use `build_images` in Pipeline
45-
DevSpace builds images when the [`build_image` function](../functions) is called
45+
### 2. Call `build_images` in Pipeline
46+
DevSpace builds images when the [`build_image` function](../functions/index.mdx#build_images) is called within `pipelines` as shown in this example:
47+
```yaml title=devspace.yaml
48+
version: v2beta1
49+
pipelines:
50+
# highlight-start
51+
build: |-
52+
build_images --all
53+
build-api: |-
54+
build_images api
55+
build-ordered: |-
56+
build_images auth
57+
build_images api payments
58+
# highlight-end
59+
60+
images:
61+
api: ... # see example above
62+
payments: ... # see example above
63+
auth: ... # see example above
64+
```
65+
4666

4767
### 3. Run Pipeline
68+
Given the example above, you can now run:
69+
- `devspace build` to build all 3 images in Parallel
70+
- `devspace run-pipeline build-api` to build only the image named `api`
71+
- `devspace run-pipeline build-ordered` to
72+
1. First build the image `auth` (blocking)
73+
2. Then build the images `api` and `payments` in parallel
4874

4975

5076
## Build Configuration
5177
DevSpace lets you customize the build process for each image using the following config fields:
5278

5379
<ConfigPartialBuildConfig/>
5480

81+
5582
### `buildArgs`
83+
Your Dockerfile can use the `ARG` instruction to define arguments that will be used in other build instructions as this example shows:
84+
```Dockerfile title=Dockerfile
85+
ARG JDK_VERSION=17
86+
FROM maven:3-openjdk-${JDK_VERSION}-slim
87+
```
88+
By default, this Dockerfile uses `maven:3-openjdk-7-slim` as base image but you can pass the build arg `JDK_VERSION` to change this dynamically.
89+
90+
There are two options to provide build args in `devspace.yaml`:
91+
92+
<details>
93+
<summary>
94+
95+
#### 1. Setting `buildArgs` in the `images` section
96+
97+
</summary>
98+
99+
```yaml title=devspace.yaml
100+
version: v2beta1
101+
images:
102+
auth:
103+
image: ghcr.io/loft-sh/devspace-example-auth
104+
# highlight-start
105+
buildArgs:
106+
JDK_VERSION: 8
107+
ANOTHER_ARG: "some other value"
108+
# highlight-end
109+
```
110+
111+
</details>
112+
113+
<details>
114+
<summary>
115+
116+
#### 2. Calling `build_images` with the `--set` flag to dynamically add or override the `buildArgs` at runtime
117+
118+
</summary>
119+
120+
```yaml title=devspace.yaml
121+
version: v2beta1
122+
pipelines:
123+
build: |-
124+
build_images --set buildArgs.JDK_VERSION=11 --set "buildArgs.SOME_ARG_NAME=some value"
125+
images:
126+
auth:
127+
image: ghcr.io/loft-sh/devspace-example-auth
128+
```
129+
130+
</details>
131+
132+
56133

57134
### `target` For Multi-Stage Builds
135+
Some Dockerfiles contain multiple `FROM` instructions that define build stages optionally using the `AS <stage-name>` suffix as shown below:
136+
```Dockerfile title=Dockerfile
137+
# highlight-next-line
138+
FROM golang:1.17-bullseye AS builder
139+
ADD . /go/src/app
140+
RUN go build -o /go/bin/app
141+
142+
# highlight-next-line
143+
FROM gcr.io/distroless/base-debian11
144+
COPY --from=builder /go/bin/app /
145+
CMD ["/app"]
146+
```
147+
Without defining a build `target`, DevSpace (just like Docker and most other build engines) would build the entire image. However, for developerment, you may not want to use the fully built image because in this case it is a distroless container that only contains the final Go binary but no development tooling, not even `sh` to be able to open a terminal inside the container via `devspace enter`.
58148

149+
If you want the image building process to only build the `builder` stage (line 1-4), then you have two options to pass a build `target`:
59150

60-
## Parallel vs Sequential Builds
151+
<details>
152+
<summary>
61153

154+
#### 1. Setting `target` in the `images` section
62155

63-
## Rebuild Strategy
156+
</summary>
64157

158+
```yaml title=devspace.yaml
159+
version: v2beta1
160+
images:
161+
auth:
162+
image: ghcr.io/loft-sh/devspace-example-auth
163+
# highlight-next-line
164+
target: builder
165+
```
65166

167+
</details>
66168

67-
## Dockerfile Overwrites
169+
<details>
170+
<summary>
171+
172+
#### 2. Calling `build_images` with the `--set` flag to dynamically add or override the `target` at runtime
173+
174+
</summary>
175+
176+
```yaml title=devspace.yaml
177+
version: v2beta1
178+
pipelines:
179+
build: |-
180+
build_images auth --set target=builder
181+
images:
182+
auth:
183+
image: ghcr.io/loft-sh/devspace-example-auth
184+
```
185+
186+
</details>
187+
188+
189+
### Dockerfile Overwrites
68190

69191

70192
<ConfigPartialOverwrites/>
193+
194+
195+
## Rebuild Strategy
196+
By default, DevSpace tries to skip building images as much as possible. Once any of your images is built once, DevSpace will only rebuild it if one of the conditions is true:
197+
- The `dockerfile` has changed
198+
- Any file within the build `context` folder has changed (while respecting `.dockerignore` rules)
199+
- The image configuration within the `devspace.yaml` has changed (including values set in the pipeline scripe, e.g. via `--set`)
200+
- The image was **not** been built before or the `.devspace/` folder has been deleted/manipulated
201+
202+
You can explicitly override this behavior using the `rebuildStrategy` field:
203+
204+
<ConfigPartialRebuildStrategy/>
205+
206+
You can also set the `rebuildStrategy` during runtime using the `--set` flag:
207+
```yaml title=devspace.yaml
208+
version: v2beta1
209+
pipelines:
210+
build: |-
211+
build_images auth --set rebuildStrategy=always
212+
```
213+
214+
:::tip `.devspace/` Folder
215+
DevSpace stores the information about each previously built image inside the `.devspace/` folder within your project. Do **not** commit this folder via `git`. It should always be listed in `.gitignore`.
216+
:::
217+
218+
219+
## `--skip-build` Flag
220+
If you call `devspace [dev/deploy/build/run-pipeline]` using the `--skip-build` flag, DevSpace will skip any `build_images` instructions defined in your pipeline script.
221+
222+
223+
## Parallel vs Sequential Builds
224+
When calling `build_images --all` or `build_images [image1] [image2]`, DevSpace builds all specified images in parallel.
225+
226+
To execute image building sequentially, call `build_images` multiple times as shown below:
227+
```yaml title=devspace.yaml
228+
version: v2beta1
229+
pipelines:
230+
build: |-
231+
build_images auth
232+
build_images api payments
233+
234+
images:
235+
api: ... # see example above
236+
payments: ... # see example above
237+
auth: ... # see example above
238+
```

‎docs/pages/configuration/images/tag.mdx‎

Lines changed: 58 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,61 @@
11
---
2-
title: Tag
2+
title: Tagging Images with DevSpace
33
sidebar_label: 2. Tag
44
---
5+
6+
DevSpace always instructs the build engine to tag any images that are being built. By default, DevSpace uses a random string to tag each image. However, you can customize how DevSpace should tag your images.
7+
8+
9+
## `build_images --tag / -t`
10+
The [`build_images` function](../functions/index.mdx#build_images) provides a `--tag / -t` flag that can be passed multiple times to the function to specify one or more tags that DevSpace should use to tag the respective images.
11+
12+
```yaml title=devspace.yaml
13+
version: v2beta1
14+
pipelines:
15+
build: |-
16+
GIT_TAG_OR_HASH=$(git describe --always)
17+
# highlight-next-line
18+
build_images api -t latest -t $GIT_TAG_OR_HASH
19+
20+
images:
21+
api: ... # see example above
22+
payments: ... # see example above
23+
auth: ... # see example above
24+
```
25+
26+
27+
## `devspace [command] --tag / -t`
28+
DevSpace also provides a `--tag / -t` flag for pipeline-based commands such as `devspace build`, `devspace deploy` or `devspace run-pipeline [name]` which is passed to every `build_images` call.
29+
30+
```bash
31+
devspace build -t latest -t $CUSTOM_HASH
32+
```
33+
34+
35+
## `tags` Field
36+
Instead of using the `--tag` flags, you can also statically define tags for each image in your `images` section and `build_images` will respect them for each image independently:
37+
38+
```yaml title=devspace.yaml
39+
version: v2beta1
40+
pipelines:
41+
build: |-
42+
build_images --all
43+
44+
images:
45+
api:
46+
image: ghcr.io/loft-sh/devspace-example-api
47+
# highlight-start
48+
tags:
49+
- dev-latest
50+
- $(git describe --always)
51+
# highlight-end
52+
payments:
53+
image: ghcr.io/loft-sh/devspace-example-payments
54+
dockerfile: ./payments/Dockerfile
55+
context: ./payments/
56+
# highlight-start
57+
tags:
58+
- some-tag
59+
- another-tag
60+
# highlight-end
61+
```

‎docs/pages/configuration/pipelines/index.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -126,11 +126,12 @@ pipelines:
126126
extraEnv=$(get_flag "env") # Retrieve the value of the `env` flag and store it in a variable
127127
echo ${extraEnv[1]}
128128

129+
TERMINAL_ENABLED=true
129130
if [ $(get_flag "logs") == "true" ]; then # Test if --logs/-l flag is used or not
130-
start_dev app --set terminal= # Remove terminal config, so DevSpace falls back to log streaming
131-
else
132-
start_dev app
131+
TERMINAL_ENABLED=false # Disable terminal, so DevSpace falls back to log streaming
133132
fi
133+
134+
start_dev app --set terminal.enabled=$TERMINAL_ENABLED
134135
```
135136

136137

‎docs/src/css/content/config-fields.scss‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,10 @@ body .markdown .config-field {
44
padding: 1em 1.4em;
55
border: 1px solid transparent;
66
border-bottom-color: #eee;
7+
border-top-color: #eee;
78

8-
&:first-of-type {
9-
border-top-color: #eee;
9+
+ .config-field {
10+
border-top-color: transparent;
1011
}
1112

1213
margin: var(--ifm-leading) 0 0;

‎docs/src/css/content/markdown.scss‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ body .markdown {
4141
}
4242

4343
.markdown h3 {
44-
margin-top: 1.8em;
44+
margin-top: 2.8em;
4545
line-height: 0.6em;
4646
}
4747

‎docs/src/css/sidebar.scss‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ body .menu {
135135
.menu__list {
136136
/* 4th level links */
137137
.menu__link {
138-
padding-left: 6.5rem;
138+
padding-left: 6rem;
139139
font-size: 0.9em;
140140

141141
&:not(.menu__link--active):not(:hover) {

0 commit comments

Comments
 (0)