diff --git a/README.md b/README.md index 3779587..2ad4e2e 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,33 @@ ## Description -[Go](https://go.dev/) (a.k.a., Golang) is a statically-typed programming language, with syntax loosely derived from C. Go offers additional features such as garbage collection, type safety, certain dynamic-typing capabilities, additional built-in types (for example, variable-length arrays and key-value maps) as well as a large standard library. +[Go](https://go.dev/) (a.k.a., Golang) is a statically-typed programming +language, with syntax loosely derived from C. Go offers additional features +such as garbage collection, type safety, certain dynamic-typing capabilities, +additional built-in types (for example, variable-length arrays and key-value +maps) as well as a large standard library. + ## Usage +We recommend using the Go image as a build environment. Thus, +the compiler does not need to be shipped as part of the images that are +deployed. Instead, we recommend to use the Go image as the +builder image only. -To compile and deploy an application, copy the sources, fetch dependencies (assuming go.mod is used for dependency management), and build the binary: +There are two options to work with Go images. First, you can encapsulate your +application in a `scratch` container image, essentially an empty filesystem +image. This approach only works if your Go application does not depend on libc +or any other library or files, as they will not be available. + +The second option uses a slim base container image with just the minimal +packages required to run the Go application. + +To compile and deploy an application, copy the sources, fetch dependencies +(assuming go.mod is used for dependency management), and build the binary using +the following Dockerfile options. + + +### Building from `scratch` ```Dockerfile # Build the application using the Go 1.22 development container image @@ -16,7 +38,8 @@ FROM registry.opensuse.org/opensuse/bci/golang:1.22 as build WORKDIR /app -# pre-copy/cache go.mod for pre-downloading dependencies and only redownloading them in subsequent builds if they change +# pre-copy/cache go.mod for pre-downloading dependencies and only +# redownloading them in subsequent builds if they change COPY go.mod go.sum ./ RUN go mod download && go mod verify @@ -24,7 +47,7 @@ COPY . ./ # Make sure to build the application with CGO disabled. # This will force Go to use some Go implementations of code -# rather than those normally supplied by the host operating system. +# rather than those supplied by the host operating system. # You need this for scratch images as those supporting libraries # are not available. RUN CGO_ENABLED=0 go build -o /hello @@ -32,9 +55,9 @@ RUN CGO_ENABLED=0 go build -o /hello # Bundle the application into a scratch image FROM scratch -COPY --from=build /hello /hello +COPY --from=build /hello /usr/local/bin/hello -CMD ["/hello"] +CMD ["/usr/local/bin/hello"] ``` Build and run the container image: @@ -58,18 +81,49 @@ To run the application tests inside a container, use the following command: $ podman run --rm -v "$PWD":/app:Z -w /app registry.opensuse.org/opensuse/bci/golang:1.22 go test -v ``` -**Note:** The Golang image should be used as a build environment. For runtime, self-contained Go binaries should use a `scratch` image and for applications that require external dependencies use the `bci-base` image. + +### Building from SLE BCI + +The [SLE BCI General Purpose Base Containers](https://opensource.suse.com/bci-docs/documentation/general-purpose-bci/) +images offer four different options for deployment, depending on your exact requirements. + +```Dockerfile +# Build the application using the Go 1.22 development Container Image +FROM registry.opensuse.org/opensuse/bci/golang:1.22 as build + +WORKDIR /app + +# pre-copy/cache go.mod for pre-downloading dependencies and only +# redownloading them in subsequent builds if they change +COPY go.mod go.sum ./ +RUN go mod download && go mod verify + +COPY . ./ + +RUN go build -o /hello + +# Bundle the application into a scratch image +FROM registry.suse.com/bci/bci-micro:15.4 + +COPY --from=build /hello /usr/local/bin/hello + +CMD ["/usr/local/bin/hello"] +``` + +The above example uses the SLE BCI micro image as the deployment image for +the resulting application. See the [SLE BCI use with Go +documentation](https://opensource.suse.com/bci-docs/guides/use-with-golang/) +for further details. + ## Additional tools -The following additional tools are included in the image: +The following tools are also included in the image: - go1.22-race - make - git-core - - ## Licensing `SPDX-License-Identifier: MIT` diff --git a/golang-stable-image.changes b/golang-stable-image.changes index f8563e4..f976066 100644 --- a/golang-stable-image.changes +++ b/golang-stable-image.changes @@ -1,3 +1,8 @@ +------------------------------------------------------------------- +Mon Jun 24 23:55:53 UTC 2024 - Dirk Mueller + +- README fixes + ------------------------------------------------------------------- Tue Jun 18 17:24:16 UTC 2024 - Dirk Mueller