Merge pull request #181 from shanejbrown/examples-build

Build Examples

Author: shanejbrown

.gitignore

@@ -20,3 +20,7 @@ buildrunner/version.py
 
 buildrunner.results
 curator.results
+
+# Ignore all .tar files
+# Manually running of some example files may create local .tar files
+*.tar

README.rst

@@ -1131,7 +1131,7 @@ See `docs/common-issues <docs/common-issues.rst>`_.
 Example Configurations
 ======================
 
-See `examples <examples/README.rst>`_.
+See `examples <examples/>`_.
 
 Contributing
 ============

examples/README.rst

@@ -14,13 +14,13 @@ To run Buildrunner using an example configuration file, follow these steps from
 2. **Execute Buildrunner with a specified configuration file:**
     .. code-block:: sh
 
-        PYTHONPATH=. ./bin/buildrunner -f examples/<path-to-config-file>
+      ./run-buildrunner.sh  -f examples/<path-to-config-file>
 
     *Example:*
 
     .. code-block:: sh
 
-      PYTHONPATH=. ./bin/buildrunner -f examples/build/basic/buildrunner.yaml
+      ./run-buildrunner.sh  examples/build/basic/buildrunner.yaml
 
 Adding a New Example Configuration File
 =======================================
@@ -39,4 +39,9 @@ To contribute a new example configuration file, adhere to the following guidelin
    - If necessary, include a ``README.rst`` file in the same directory as the configuration file to provide additional details or instructions.
    - Any supporting files required for the configuration should be placed alongside the configuration file.
 
-Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users.
+Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users.
+
+Excluding Example Configuration Files from Unit Tests
+=====================================================
+
+To exclude an example configuration file from unit tests, add the file path to the ``excluded_example_files`` list in ``tests/test_buildrunner_files.py``.

examples/build/basic/buildrunner.yaml

@@ -3,5 +3,5 @@ steps:
   simple-build-step:
     build:
       dockerfile: |
-        FROM busybox:latest
+        FROM alpine:latest
         RUN echo Hello World

examples/build/buildargs/buildrunner.yaml

@@ -0,0 +1,18 @@
+# This example demonstrates how to use the buildargs field in the build step.
+# The buildargs field allows you to pass build-time variables to the Dockerfile.
+steps:
+  buildargs-step:
+    build:
+      buildargs:
+        MY_VERSION: 2.0
+      dockerfile: |
+        FROM alpine:latest
+        ARG MY_VERSION
+        LABEL version=$MY_VERSION
+
+    # To view the label in the built image do the following:
+    #  1. Uncomment the following 'push:' line
+    #  2. Run 'PYTHONPATH=. ./bin/buildrunner -f examples/build/buildargs/buildrunner.yaml'
+    #  3. Run 'docker image inspect my-images/buildargs-image:latest' to see the label.
+    #
+    # push: my-images/buildargs-image:latest

examples/build/cache/buildrunner.yaml

@@ -0,0 +1,16 @@
+# Description: This example demonstrates how to use the no-cache option in the build step.
+steps:
+  cache-build-step:
+    build:
+      no-cache: false
+      dockerfile: |
+        FROM alpine:latest
+        RUN apk update
+        RUN echo Hello World
+  no-cache-build-step:
+    build:
+      no-cache: true
+      dockerfile: |
+        FROM alpine:latest
+        RUN apk update
+        RUN echo Hello World

examples/build/import/buildrunner.yaml

@@ -0,0 +1,11 @@
+# This example demonstrates how to import a tarball image in the build step.
+# This requires the tarball image to be present in the same directory where buildrunnner is executed.
+# Before running this example, make sure to create a tarball image using the following command:
+# docker save alpine:latest -o alpine.tar
+#
+# WARNING: Do not commit the tarball image to the repository.
+#
+steps:
+  import-step:
+    build:
+      import: alpine.tar

examples/build/inject/buildrunner.yaml

@@ -0,0 +1,14 @@
+# This example demonstrates how to use the inject field to inject a file into the build context.
+# See buildrunner documentation for more information.
+steps:
+  build-step-with-inject:
+    build:
+      inject:
+        # Step 1: Inject a file into the build context
+        # The file /injectfile.txt will be injected into the build context
+        examples/build/inject/injectfile.txt: /injectfile.txt
+      dockerfile: |
+        FROM alpine
+        # Step 2: Copy the injected file into the image or use it in some other way in the build process
+        COPY /injectfile.txt /tmp/
+        RUN cat /tmp/injectfile.txt

examples/build/inject/injectfile.txt

@@ -0,0 +1 @@
+This is a sample text file that can be injected into the build context

examples/build/platform/README.rst

@@ -0,0 +1 @@
+Contains an example of building a single-platform image.