Code review from @RomainMuller

Author: eliottness

content/en/security/application_security/setup/go/dockerfile.md

@@ -17,8 +17,8 @@ further_reading:
 
 # Introduction
 
-App and API Protection for Go installation requirements can be abstract and the Go toolchain
-cross-compilation capabilities can make it hard to understand what has to be done precisely.
+App and API Protection for Go installation requirements can be abstract. Moreover the Go toolchain
+cross-compilation and CGO capabilities can make it hard to understand what has to be done precisely.
 
 In these cases, a more precise way to materialize these examples like a Dockerfile can be interesting.
 The goal of this guide is to be a step-by-step guide to a working Dockerfile, tailor-fitted for your usecase.
@@ -40,37 +40,35 @@ FROM golang:1 AS build
 WORKDIR /app
 COPY . .
 
-RUN go install github.com/DataDog/orchestrion@latest && \
-    orchestrion pin
+RUN go install github.com/DataDog/orchestrion # Resolved from go.mod dependencies
 
 RUN orchestrion go build -o main .
 
-FROM ubuntu:noble
+FROM debian:bookworm
 COPY --from=build /app/main /usr/local/bin
 
 ENV DD_APPSEC_ENABLED=true
 ENTRYPOINT [ "/usr/local/bin/main" ]
 ```
 
-This constitutes the simplest version of a working Dockerfile for a Go application with Datadog's WAF enabled.
-It would be better to run `orchestrion pin` ahead of time and commit it to your VCS for future builds, but this is not a strict requirement.
+This constitutes the simplest version of a working Dockerfile for a Go application with Datadog's WAF enabled. If this is your first use of [Orchestrion][5]. This dockerfile requires to run `orchestrion pin` beforehand and commit the resulting changes for it to work. Please refer to our [Getting Started for Go][-]
 
 This Dockerfile is split into two stages:
 1. The build stage builds from an Debian image the Go application using the [Orchestrion][5] tool to instrument it with App and API Protection features.
 2. The runtime stage copies the built application into a minimal Ubuntu image and sets the environment variable `DD_APPSEC_ENABLED` to `true` to enable App and API Protection.
 
-This two-stage build process is beneficial because it allows you to keep the final image small and free of unnecessary build tools,
-while still ensuring that your application is instrumented correctly for App and API Protection.
+This two-stage build process is beneficial because it allows you to keep the final image small and free of unnecessary build tools.
+While still ensuring that your application is instrumented correctly for App and API Protection.
 
 The following sections show different Dockerfile scenarios, each with their specific considerations and complete examples.
 
 ## Dockerfile scenarios
 
 Two main dimensions impact your Dockerfile choice for App and API Protection:
 * **libc implementation**: glibc (Debian/Ubuntu) or musl (Alpine)
-* **CGO**: enabled (default) or disabled (`CGO_ENABLED=0`)
+* **CGO**: enabled or disabled (with the env var `CGO_ENABLED`).
 
-These dimensions affect both build requirements and runtime compatibility. The Datadog WAF requires specific shared libraries (`libc.so.6` and `libpthread.so.0`) at runtime, and the build approach varies depending on these choices. When CGO is enabled, those libraries will always be required so the Datadog WAF can be baked in without issue. But CGO being disabled is often synonymous with no shared library, which cannot be the case out-of-the-box for Datadog WAF. This is why, by default, when CGO is disabled, the `-tags appsec` flag need to be passed. 
+These dimensions affect both build requirements and runtime compatibility. The Datadog WAF requires specific shared libraries (`libc.so.6` and `libpthread.so.0`) at runtime, and the build approach varies depending on these choices. Those dependencies are required by all programs built with CGO enabled, so the Datadog WAF will work out-of-the-box on runtime environments that support such programs. When CGO is disabled however, Go usually produces a fully statically linked binary that does not require these libraries but this is not true when using the Datadog WAF, which is why when CGO is disabled, the `-tags=appsec` flag needs to be passed in order for the Datadog WAF to be enabled.
 
 ### Standard glibc-based Dockerfile
 
@@ -82,7 +80,7 @@ FROM golang:1 AS build
 WORKDIR /app
 COPY . .
 
-RUN go install github.com/DataDog/orchestrion@latest
+RUN go install github.com/DataDog/orchestrion
 RUN orchestrion go build -o main .
 
 FROM ubuntu:noble
@@ -108,7 +106,7 @@ FROM golang:1 AS build
 WORKDIR /app
 COPY . .
 
-RUN go install github.com/DataDog/orchestrion@latest
+RUN go install github.com/DataDog/orchestrion
 RUN orchestrion go build -o main .
 
 FROM alpine
@@ -134,7 +132,7 @@ FROM golang:1-alpine AS build
 WORKDIR /app
 COPY . .
 
-RUN go install github.com/DataDog/orchestrion@latest
+RUN go install github.com/DataDog/orchestrion
 RUN orchestrion go build -tags appsec -o main .
 
 FROM alpine
@@ -157,7 +155,7 @@ FROM golang:1 AS build
 WORKDIR /app
 COPY . .
 
-RUN go install github.com/DataDog/orchestrion@latest
+RUN go install github.com/DataDog/orchestrion
 
 # Build with appsec tag for CGO-disabled builds
 ENV CGO_ENABLED=0
@@ -182,14 +180,14 @@ ENTRYPOINT [ "/main" ]
 
 ### Distroless Dockerfile
 
-For security-focused deployments using Google's distroless images:
+For security-focused deployments using [Google's distroless][7] images:
 
 ```dockerfile
 FROM golang:1 AS build
 WORKDIR /app
 COPY . .
 
-RUN go install github.com/DataDog/orchestrion@latest
+RUN go install github.com/DataDog/orchestrion
 
 ENV CGO_ENABLED=0
 RUN orchestrion go build -tags appsec -o main .
@@ -223,7 +221,7 @@ RUN apt-get update && apt-get install -y gcc-aarch64-linux-gnu
 WORKDIR /app
 COPY . .
 
-RUN go install github.com/DataDog/orchestrion@latest
+RUN go install github.com/DataDog/orchestrion
 
 # Cross-compile for ARM64
 ENV CGO_ENABLED=1 CC=aarch64-linux-gnu-gcc GOOS=linux GOARCH=arm64
@@ -241,9 +239,9 @@ ENTRYPOINT [ "/usr/local/bin/main" ]
 * The runtime stage must match the target architecture
 * CGO must be enabled for proper WAF integration
 
-## Run your application
+## Try it out
 
-Now that the docker image is ready, run [appsec-go-test-app][4]:
+Most of these Dockerfiles are availabe in [appsec-go-test-app][4], trying them out is very easy:
 
 ```sh
 docker build -f ./examples/alpine/Dockerfile -t appsec-go-test-app .
@@ -260,3 +258,5 @@ docker run appsec-go-test-app
 [3]: https://github.com/DataDog/appsec-go-test-app/blob/main/examples/docker
 [4]: https://github.com/DataDog/appsec-go-test-app
 [5]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/go/?tab=compiletimeinstrumentation
+[6]: /security/application_security/setup/go/setup
+[7]: https://github.com/GoogleContainerTools/distroless