diff --git a/.gitignore b/.gitignore index 9667c27..a043ba3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ /.hugo_build.lock /public/ -.vscode \ No newline at end of file +/resources/ +.vscode diff --git a/content/guides/building-on-top-of-bci.adoc b/content/guides/building-on-top-of-bci.adoc new file mode 100644 index 0000000..3774768 --- /dev/null +++ b/content/guides/building-on-top-of-bci.adoc @@ -0,0 +1,309 @@ +--- +title: Building Container Images Based on SLE BCI +--- + +In the container ecosystem, many tools can work with OCI-compliant images, +and all of them can use our Base Container Images. + +== Using with Docker, Podman or nerdctl + +The Base Container Images are OCI-compliant, and you can use them +directly in your `Dockerfile` or `Containerfile` without any modifications. +All you need to do is include the image in the `FROM` line as follows: + +[source,Dockerfile] +---- +FROM registry.suse.com/bci/nodejs:latest as node-builder +WORKDIR /app/ +COPY . /app/ + +RUN npm install && npm run build +---- + +Build it with your favorite container runtime: +{{< tabs "build_container_image">}} +{{< tab "Docker">}} +[source,Shell] +---- +docker build -t my-app . +---- +{{< /tab >}} +{{< tab "Podman" >}} +[source,Shell] +---- +podman build -t my-app . +---- +{{< /tab >}} +{{< tab "nerdctl" >}} +[source,Shell] +---- +nerdctl build -t my-app . +---- +{{< /tab >}} +{{< /tabs >}} + +== Using the Open Build Service + +The https://openbuildservice.org/[Open Build Service] (OBS) lets you build container images, +as explained in the https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.build_containers.html[documentation]. +It supports Docker, Podman and https://osinside.github.io/kiwi/[KIWI] as back-ends. + +The examples below require a project where you have write access and https://github.com/openSUSE/osc/[osc]. +Your home project (`home:`) is sufficient for this exercise. + +=== Building a container using Docker or Podman + +To build a Dockerfile-based container image in OBS, +follow the steps below. + +[arabic] +. Create a new package for your container. ++ +[source,ShellSession] +---- +osc checkout home:your-username && cd home:your-username +osc mkpac my-container-image && cd my-container-image +---- + +[arabic, start=2] +. Add a repository to the project with `osc`. +The repository name is `containerfile` by convention. +This allows OBS to fetch resources used to build containers. ++ +[source,ShellSession] +---- +osc meta -e prj +---- +Insert the following XML into the project settings: ++ +[source,xml] +---- + + + + x86_64 + aarch64 + s390x + ppc64le + +---- ++ +The path `SUSE:Registry` allows the use of images from the SUSE Registry in OBS. +The path `SUSE:SLE-15-SP7:Update` allows the container to use packages from SLE. +Depending on the SLE version that you are targeting in your container, this path needs +adjustment. + +[arabic, start=3] +. Add a configuration to the project with `osc`. +This will configure OBS to use Docker or Podman to build +packages in the `containerfile` repository. ++ +[source,ShellSession] +---- +osc meta -e prjconf +---- +Insert the following into the project configuration: ++ +[source,console] +---- +%if %_repository == "containerfile" +# OBS supports the following engines as backend: +# - podman +# - docker +Type: podman +%endif +---- +[arabic, start=4] +. Create a `Dockerfile` inside the package `my-container-image`. +Set the base image using `FROM`, as usual. ++ +[source,Dockerfile] +---- +FROM registry.suse.com/bci/bci-base:15.7 +---- + +[arabic, start=5] +. Set the build tags using comments in the `Dockerfile`. ++ +[source,Dockerfile] +---- +#!BuildTag: my-build-tag:latest +#!BuildTag: my-build-tag:0.1 +#!BuildTag: my-other-build-tag:0.1 +---- ++ +The `BuildTag` is the equivalent image name (or tag) assigned during the build process. +Since OBS invokes Docker or Podman itself, it has the same effect as the following command: ++ +[source,ShellSession] +---- +podman build -t my-build-tag:latest -t my-build-tag:0.1 -t my-other-build-tag:0.1 . +---- +A complete `Dockerfile` would look like this: ++ +[source,Dockerfile] +---- +#!BuildTag: my-app:latest +#!BuildTag: my-app:0.0.1 + +FROM registry.suse.com/bci/bci-base:15.7 + +WORKDIR /src + +RUN zypper -n install --no-recommends make gcc + +COPY . . + +RUN make + +CMD ["./my-app"] +---- + +=== Building a container using KIWI + +https://osinside.github.io/kiwi/[KIWI] is a generic image-building tool +that also supports building container images. It is tightly integrated +into the Open Build Service as the standard image builder. + +To build a KIWI-based container image in OBS, +follow the steps below. + +[arabic] +. Create a new package for your container. ++ +[source,ShellSession] +---- +osc checkout home:your-username && cd home:your-username +osc mkpac my-kiwi-container && cd my-kiwi-container +---- + +[arabic, start=2] +. Add a repository to the project with `osc`. +The repository name is `containerkiwi` by convention. +This allows OBS to fetch resources used to build containers. ++ +[source,ShellSession] +---- +osc meta -e prj +---- +Insert the following XML into the project settings: ++ +[source,xml] +---- + + + + x86_64 + aarch64 + s390x + ppc64le + +---- ++ + +[arabic, start=3] +. Add a configuration to the project with `osc`. +This will configure OBS to KIWI to build +packages in the `containerkiwi` repository. ++ +[source,ShellSession] +---- +osc meta -e prjconf +---- +Insert the following into the project configuration: ++ +[source,console] +---- +%if "%_repository" == "containerkiwi" +Type: kiwi +Repotype: none +Patterntype: none + +Prefer: -libcurl4-mini +Prefer: -systemd-mini +Prefer: -libsystemd0-mini +Prefer: -libudev-mini1 +Prefer: -udev-mini +Prefer: kiwi-boot-requires +Prefer: sles-release +Prefer: sles-release-MINI +Prefer: python3-kiwi + +Preinstall: !rpm rpm-ndb +Substitute: rpm rpm-ndb +Binarytype: rpm +%endif +---- + +[arabic, start=4] +. Create a `kiwi.xml` inside the package `my-kiwi-image`. ++ +[source,xml] +---- + + + + + + + + + + + + + + + 15.7.0 + zypper + true + + + + + + + + + + +---- + +=== Building images based on your images + +You can build containers in OBS that are based on other containers that +have been built in OBS as well. + +If the image you want to use is in the same project and repository as the +image that you are building, there's no need to configure any extra repositories. + +However, if the image comes from another project or repository, you need to adjust +your repository configuration. Add the desired repository path to the project with `osc`. +Previously, we added the repositories `containerfile` and `containerkiwi` to use the SLE BCI +images. Now we are going to include another project path. + +[source,ShellSession] +---- +osc meta -e prj +---- + +Adjust the `containerfile` or `containerkiwi` XML to include a new path: + +[source,xml] +---- + + + + + x86_64 + aarch64 + s390x + ppc64le + +---- + +As shown in the previous sections, now you can use other images similarly to SLE BCI. diff --git a/content/guides/building-on-top-of-bci/_index.adoc b/content/guides/building-on-top-of-bci/_index.adoc deleted file mode 100644 index b6eac9b..0000000 --- a/content/guides/building-on-top-of-bci/_index.adoc +++ /dev/null @@ -1,363 +0,0 @@ ---- -title: Building Container Images based on SLE BCI -slug: building-on-top-of-bci -resources: - - name: registry.opensuse.org_bci_ruby - src: "registry.opensuse.org_bci_ruby.png" - title: Ruby SLE BCI on registry.opensuse.org - - name: obs_repository_add - src: "obs_repository_add.png" - title: repository view - - name: registry.opensuse.org_bci_ruby_build_tag - src: "registry.opensuse.org_bci_ruby_build_tag.png" - title: Ruby SLE BCI on registry.opensuse.org with the build tag underlined ---- - -{{< hint title=Summary >}} -Many tools for building container images exist in the ecosystem and -our Base Container Images can be used by all of them. This guide -summarizes the most important ones for our users: - -* link:#_using_docker_podman_and_nerdctl[Locally using docker, podman, or -nerdctl] -* link:#_building_from_a_dockerfile_using_docker_or_podman[Docker or -Podman in the Open Build Service] -* link:#_building_a_derived_container_image_using_kiwi[Kiwi in the -Open Build Service] -{{< /hint >}} - -== Using docker, podman and nerdctl - -The SLE Base Container Images are OCI compliant images and can thus be -used without any modifications in your `Dockerfile`. Visit -https://registry.suse.com[registry.suse.com], find the container image -that fits your needs, and include it in the `FROM` line in your -`Dockerfile` as follows: - -[source,Dockerfile] ----- -FROM registry.suse.com/bci/node:16 as node-builder -WORKDIR /app/ -COPY . /app/ - -RUN npm install && npm run build ----- - -Build it with your favorite container runtime: -{{< tabs "build_container_image">}} -{{< tab "Docker">}} -[source,Shell] ----- -docker build . ----- -{{< /tab >}} -{{< tab "Podman" >}} -[source,Shell] ----- -buildah bud --layers . ----- -{{< /tab >}} -{{< tab "nerdctl" >}} -[source,Shell] ----- -nerdctl build . ----- -{{< /tab >}} -{{< /tabs >}} - -== Using the Open Build Service - -The https://openbuildservice.org/[Open Build Service] can be used to -build container images, as explained in the -https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.build_containers.html[documentation]. -It supports building container images using Docker, Podman or -https://osinside.github.io/kiwi/[kiwi]. - -=== Building from a `Dockerfile` using docker or podman - -The Open Build Service supports building container images using a -`Dockerfile`. However, you need to pay particular attention when -creating offline builds with the Open Build Service. To build a -container image based on SLE BCI follow the steps below. - -1. Create a new package for a container image in an appropriate - project where you have write access using - https://github.com/openSUSE/osc/[`osc`]: -+ -[source,ShellSession] ----- -❯ cd /path/to/the/project/ -❯ osc mkpac my-container-image && cd my-container-image ----- - -[arabic, start=2] -. Create a new repository for building container images for the - project called `containerfile` by convention. -+ -Create this repository by inserting the following XML snippet into the -project settings via `osc meta -e prj`: -+ -[source,xml] ----- - - - - x86_64 - aarch64 - s390x - ppc64le - ----- -+ -Depending on the SLE version that you are targeting, you will have to -adjust the version in line 3. - -[arabic, start=3] -. Add the following snippet into the project configuration. You can edit -the project configuration via `osc meta -e prjconf`: -+ -[source,console] ----- -%if %_repository == "containerfile" -# if you prefer docker, use the following line or if you want to build using -# podman, replace docker with podman -Type: docker -%endif ----- - -[arabic, start=4] -. Create a `Dockerfile` inside your the package `my-container-image` and -set the base image of your container image using `FROM` as usual. The -only difference is that you have to omit the `registry.suse.com` from -the BCI URL and only use the build tag as illustrated below: -+ -{{< tabs "dockerfiles_from">}} -{{< tab "bci-base">}} -[source,Dockerfile] ----- -FROM bci/bci-base:15.4 ----- -{{< /tab >}} -{{< tab "python" >}} -[source,Dockerfile] ----- -FROM bci/python:3.10 ----- -{{< /tab >}} -{{< tab "openjdk" >}} -[source,Dockerfile] ----- -FROM bci/openjdk:17 ----- -{{< /tab >}} -{{< /tabs >}} - -[arabic, start=5] -. Set the build tags using comments in the `Dockerfile`. A build tag is -the equivalent of the `-t` flag passed to `docker build` on the command -line. Since the Open Build Service invokes `docker build` itself, it has -to take the build tags from some other place and the `Dockerfile` is -used for that as shown below: -+ -[source,Dockerfile] ----- -#!BuildTag: my-build-tag:latest -#!BuildTag: my-build-tag:0.1 -#!BuildTag: my-other-build-tag:0.6 ----- -+ -Which is equivalent to invoking `docker build` as follows: -+ -[source,ShellSession] ----- -❯ docker build -t my-build-tag:latest -t my-build-tag:0.1 -t my-other-build-tag:0.6 . ----- - -=== Building a derived container image using kiwi - -https://osinside.github.io/kiwi/[kiwi] is a generic image building tool -that also supports building container images. It is tightly integrated -into the Open Build Service as the standard image builder. - -Building a container image based on SLE BCI is outlined in the following -steps: - -[arabic] -. Create a new package for your container image in an appropriate -project where you have write access using -https://github.com/openSUSE/osc/[`osc`]: -+ -[source,ShellSession] ----- -❯ cd /path/to/the/project/ -❯ osc mkpac my-kiwi-container && cd my-kiwi-container ----- - -[arabic, start=2] -. Create a new repository for building container images for your -project. Repositories building using kiwi are called `images` by -convention and that name will be used below as well. If you pick a -different repository name, be sure to adjust it in all other places as -well. -+ -Create this repository by inserting the following xml snippet into the -project settings via `osc meta -e prj`: -+ -[source,xml] ----- - - - - x86_64 - aarch64 - s390x - ppc64le - ----- -+ -Depending on the SLE version that you are targeting, you will have to -adjust the version in line 3. - -[arabic, start=3] -. Add the following snippet into the project configuration. You can edit -the project configuration via `osc meta -e prjconf`: -+ -[source,console] ----- -%if "%_repository" == "images" -Type: kiwi -Repotype: none -Patterntype: none - -Prefer: -libcurl4-mini -Prefer: -systemd-mini -Prefer: -libsystemd0-mini -Prefer: -libudev-mini1 -Prefer: -udev-mini -Prefer: kiwi-boot-requires -Prefer: sles-release -Prefer: sles-release-MINI -Prefer: python3-kiwi - -Preinstall: !rpm rpm-ndb -Substitute: rpm rpm-ndb -Binarytype: rpm -%endif ----- - -[arabic, start=4] -. Create a `kiwi.xml` inside the package `my-kiwi-image`. Refer to a -BCI using its build tag, where you prefix it with `obsrepositories` -and replace the `:` with a `#` as outlined in the following examples: -+ -{{< tabs "kiwifiles_from">}} -{{< tab "bci-base">}} -[source,xml] ----- - - - - - - - - - ----- -{{< /tab >}} -{{< tab "python" >}} -[source,xml] ----- - - - - - - - - - ----- -{{< /tab >}} -{{< tab "openjdk" >}} -[source,xml] ----- - - - - - - - - - ----- -{{< /tab >}} -{{< /tabs >}} - -[arabic, start=5] -. Set the build tags using comments in `kiwi.xml`: -+ -[source,xml] ----- - ----- - -=== Building Container Images based on your own images - -You can build Container Images in the Open Build Service that are -based on other Images that you have been build in the Build Service as -well. Proceed for this as follows: - -[arabic] -. _Skip this step if your image is in the same project and repository as -the image that you are building._ -+ -Find the project and the repository corresponding to the container image -that you would like to use as the base. You can leverage -https://registry.opensuse.org/cgi-bin/cooverview[registry.opensuse.org] -for that by searching for container image and extracting the project and -repository names (underlined in mint green and waterhole blue -respectively): -+ -{{< img name="registry.opensuse.org_bci_ruby" size="large" >}} -+ -Add this project and repository to your project's repository -configuration either by inserting a path entry via `osc meta -e prj`: -+ -[source,xml] ----- - - - - - ----- -+ -Alternatively, you can add this repository via the web interface. For -that navigate to the project's home page in the Open Build Service and -click on the `Repositories` tab. There, find the repository in which -you build your container image, click on the green plus icon and enter -the project name and the repository name in the appearing popup: -+ -{{< img name="obs_repository_add" size="tiny" >}} - -[arabic, start=2] -. Use the build tag of the container image in the `FROM` instruction in -your `Dockerfile`. The build tag can be found in the `Dockerfile` of the -container image via the comment `#!BuildTag: $TAG` or in a kiwi xml -description via the comment: -+ -[source,console] ----- - ----- -+ -A simpler way is to go to -https://registry.opensuse.org/cgi-bin/cooverview[registry.opensuse.org] -and find the container image. The path on `registry.opensuse.org` is -constructed from the images project, repository and build tag as -outlined in the image below (the project is underlined in mint green, -the repository in waterhole blue and the build tag in persimmon): -+ -{{< img name="registry.opensuse.org_bci_ruby_build_tag" size="large" >}} diff --git a/content/guides/building-on-top-of-bci/obs_repository_add.png b/content/guides/building-on-top-of-bci/obs_repository_add.png deleted file mode 100644 index 46651c3..0000000 Binary files a/content/guides/building-on-top-of-bci/obs_repository_add.png and /dev/null differ diff --git a/content/guides/building-on-top-of-bci/registry.opensuse.org_bci_ruby.png b/content/guides/building-on-top-of-bci/registry.opensuse.org_bci_ruby.png deleted file mode 100644 index 55d59dc..0000000 Binary files a/content/guides/building-on-top-of-bci/registry.opensuse.org_bci_ruby.png and /dev/null differ diff --git a/content/guides/building-on-top-of-bci/registry.opensuse.org_bci_ruby_build_tag.png b/content/guides/building-on-top-of-bci/registry.opensuse.org_bci_ruby_build_tag.png deleted file mode 100644 index b4628a1..0000000 Binary files a/content/guides/building-on-top-of-bci/registry.opensuse.org_bci_ruby_build_tag.png and /dev/null differ