document support for services reference as additional_contexts

Signed-off-by: Nicolas De Loof <[email protected]>

Author: ndeloof

content/manuals/compose/how-tos/depent-images.md

@@ -0,0 +1,135 @@
+---
+description: Build images for services with shared definition
+keywords: compose, build
+title: Build dependent images
+weight: 50
+---
+
+{{< introduced compose 2.22.0 "/manuals/compose/releases/release-notes.md#2220" >}}
+
+To reduce push/pull time and image weight, a common practice for compose applications is to have services
+share base layers as much as possible. You will typically select the same operating system base image for
+all services. But you also can get one step further sharing image layers when your images share the system
+system packages. The challenge to address is then to avoid repeating the exact same Dockerfile instruction 
+in all services.
+
+Foe illustration, in this article we will consider you want all your services to be built on `alpine` base
+image and install system package `openssl`
+
+## Multi-stage Dockerfile
+
+Recommended approach is to group shared declaration in a single Dockerfile, and use multi-stage feature
+so that service images are built from this shared declaration
+
+
+Dockerfile:
+```
+FROM alpine as base
+RUN /bin/sh -c apk add --update --no-cache openssl
+
+FROM base as service_a
+# build service a
+...
+
+FROM base as service_b
+# build service b
+...
+```
+
+compose.yaml:
+```yaml
+services:
+  a:
+     build:
+       target: service_a
+  b:
+     build:
+       target: service_b
+```
+
+## Use another service image as base image
+
+A popular pattern is to reuse a service image as base image in another service.
+As Compose does not parse the `Dockerfile`, it can't automatically detect this dependency 
+between services to correctly order the build execution.
+
+
+a.Dockerfile:
+```
+FROM alpine
+RUN /bin/sh -c apk add --update --no-cache openssl
+```
+
+b.Dockerfile:
+```
+FROM service_a
+# build service b
+```
+
+compose.yaml:
+```yaml
+services:
+  a:
+     image: service_a 
+     build:
+       dockerfile: a.Dockerfile
+  b:
+     image: service_b
+     build:
+       dockerfile: b.Dockerfile
+```
+
+
+Legacy Docker Compose v1 used to build images sequentially, which made this pattern usable
+out of the box. Compose v2 uses buildkit to optimise build and build images in parallel. 
+Covering this usage requires an explicit declarartion.
+
+Recommendend approach is to declare dependent base image as an additional build context:
+
+compose.yaml
+```yaml
+services:
+  a:
+     image: service_a
+     build: 
+       dockerfile: a.Dockerfile
+  b:
+     image: service_b
+     build:
+       context: b/
+       dockerfile: b.Dockerfile
+       additional_contexts:
+         # `FROM service_a` will be resolved as a dependency on service a which has to be built first
+         service_a: "service:a"  
+```
+
+
+## Build with Bake
+
+Using [bake](../../build/bake/_index.md) allows to pass the complete build definition for all service
+and to orchestrate build execution in the most efficient way. 
+
+To enable this feature, run compose with `COMPOSE_BAKE=true` variable set in your environment.
+
+```
+$ COMPOSE_BAKE=true docker compose build
+[+] Building 0.0s (0/1)                                                         
+ => [internal] load local bake definitions                                 0.0s
+...
+[+] Building 2/2 manifest list sha256:4bd2e88a262a02ddef525c381a5bdb08c83  0.0s
+ ✔ service_b  Built                                                        0.7s 
+ ✔ service_a  Built    
+```
+
+Bake can also be selected as default builder by editing yout `$HOME/.docker/config.json` config file:
+```json
+{
+  ...
+  "plugins": {
+    "compose": {
+      "build": "bake"
+    }
+  }
+  ...
+}
+```