Merge pull request #5 from redhat-scholars/quarkus

Build and Create Quarkus app

documentation/modules/ROOT/pages/building-images-python.adoc

@@ -0,0 +1,123 @@
+= Building Images in Podman Desktop
+include::_attributes.adoc[]
+
+Fantastic, let's start the Podman Desktop tutorial with the most basic step in the inner loop development process: *building container images*. We'll also cover authenticating to registries amd pulling images.
+
+// TIP: Feel free skip and simply xref:building-images.adoc#pulling.adoc[pull the container images] without downloading the application source code.
+
+== Demo Application
+
+For this exercise, we'll be using a basic Java web application based on the https://quarkus.io[SuperSonic, Subatomic Quarkus] stack. The application uses a Redis cache to store the number of times we've visited the webpage. This is a simple microservice, but it's a good example of a multi-container application.
+
+image::podman-desktop-python-app-browser.png[Podman Desktop Python App, 600]
+
+== Getting Started with the Source Code
+
+Let's start off with downloading the source code for the demo application, found https://github.com/redhat-developer/podman-desktop-demo[here on GitHub]. This repository contains a variety of different Podman related demos you can try later, including Minikube, WASM, Compose, and more!
+
+image::podman-desktop-demo-repo.png[Podman Desktop Demo Repo, 600]
+
+While you could eg. clone the repository to a local machine using https://desktop.github.com/[GitHub Desktop], today let's use the command line to clone the repository. Open up the terminal, and use the noNVC menu to copy these next two commands to your clipboard, and paste/execute them.
+
+[.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+git clone https://github.com/redhat-developer/podman-desktop-demo
+----
+
+image::podman-desktop-demo-cloned.png[Podman Desktop Demo Cloned, 600]
+
+Now, let's open up the project in our IDE and take a look at the source code of the demo application, found in the `podman-desktop-demo/primary-podify-demo/front` directory.
+
+[.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+cd podman-desktop-demo/primary-podify-demo/front && code .
+----
+
+image::podman-desktop-demo-source-code.png[Podman Desktop Demo Source Code, 600]
+
+We're using Flask as a Python framework to serve the web application, as you can see from the `app.py` file. However, more important is the `Dockerfile` in the project directory, which is used to build the container image for the web application, like a recipe:
+
+* *Base Image:*
+** `FROM registry.access.redhat.com/ubi9/ubi:9.2-755 AS ubi-builder` (Starts with Red Hat's https://catalog.redhat.com/software/base-images[UBI] image)
+
+* *Build Stage:*
+** `RUN ...` (Installs tools like Python)
+** `COPY ./entrypoint.sh ...` (Copies entrypoint script for when the container starts, for Redis)
+
+* *App Preparation:*
+** `FROM scratch as python-builder` (Starts fresh, minimal image)
+** `COPY --from=ubi-builder ...` (Copies only built essentials)
+** `RUN ...` (Creates non-root user)
+** `COPY requirements.txt ...` (Copies Python dependencies)
+** `RUN pip install ...` (Installs dependencies)
+** `COPY app.py ...` (Copies app source code)
+
+* *Final Image:*
+** `FROM scratch` (Starts with minimal scratch image)
+** `COPY --from=python-builder ...` (Copies prepared application)
+** `EXPOSE 5000` (Opens port for access)
+** `USER 1000` (Switches to non-root user)
+** `ENV ...` (Sets Flask environment variables)
+** `ENTRYPOINT ["/entrypoint.sh"]` (Defines container startup command) 
+
+NOTE: While this isn't a basic Dockerfile, it's a good example of a multi-stage build with security best practices, and allows for a smaller final image.
+
+== Building the Container Image
+
+Now that we've taken a look at the source code and Dockerfile, let's build the container image from within Podman Desktop. From the *Images* section, click the *Build* button in the top right corner.
+
+image::podman-desktop-build-image-button.png[Podman Desktop Build Image, 600]
+
+This will open up a new window where we can specify the Dockerfile (=Containerfile), the build context, and image name. Let's select the `Dockerfile`, the build directory as `primary-podify-demo/front`, and `python-app` for the image name. 
+
+NOTE: The build context is the directory where the source code and Dockerfile are located, and the Dockerfile is the recipe for building the container image. We can use Podman Desktop to easily rename/retag the image later, so don't worry too much about the image name for now.
+
+image::podman-desktop-build-image-window.png[Podman Desktop Build Image Window, 600]
+
+After clicking *Build*, Podman Desktop will start building the container image, and you can see the build logs in the bottom pane. This will take a few minutes, as it's downloading the base image, installing dependencies, copying the source code, etc.
+
+image::podman-desktop-build-image-logs.png[Podman Desktop Build Image Logs, 600]
+
+Once the build is complete, you should see the new `python-app` image in the *Images* section of Podman Desktop. You'll see the default image https://www.redhat.com/sysadmin/container-image-short-names[short name] here, which we'll retag for our registry in the next section.
+
+image::podman-desktop-built-image.png[Podman Desktop Built Image, 600]
+
+
+[#pulling]
+=== Optional: Pulling the Python App Image
+
+If you'd like to skip the build process from above, you can pull the `quay.io/podman-desktop-demo/podify-demo-frontend:v1` image from a public registry. This is the same image we just built, but it's already available for use. Head to the *Images* section, and click the *Pull* button in the top right corner.
+
+[.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+quay.io/podman-desktop-demo/podify-demo-frontend:v1
+----
+
+image::podman-desktop-built-image-layers.png[Podman Desktop Built Image, 600]
+
+TIP: Due to its popularity, Podman uses the Docker Hub registry to pull images by default. However, you can authenticate other registries in the Podman Desktop *Settings > Registries*, or set defaults via the https://www.redhat.com/sysadmin/manage-container-registries[Podman registry configuration file].
+
+== Pulling the Redis Image
+
+As you may have seen from the Python web application source code, we're using a Redis cache to store the number of times we've visited the webpage. Redis is a popular choice for caching in containerized applications. The Python web application actually has a hard dependency on the Redis service, so if the Redis service is not available, the container would crash.
+
+image::podman-desktop-redis-image-start.png[Podman Desktop Redis Image, 600]
+
+Fortunately we can also run a Redis container next to our Python application. Let's go ahead and pull a pre-built Redis image from Quay.io by clicking the *Pull* button from the top right corner menu. We'll be pulling an image of Redis that has been built with the Red Hat https://catalog.redhat.com/software/base-images[UBI] and Redis installed on top.
+
+[.console-input][.console-input]
+[source,bash,subs="+macros,+attributes"]
+----
+quay.io/podman-desktop-demo/podify-demo-backend:v1
+----
+
+image::podman-desktop-redis-image-layers.png[Podman Desktop Redis Image, 600]
+
+TIP: The Dockerfile used to build the Redis image is available in the `podman-desktop-demo/primary-podify-demo/back` directory, but can also be found here. https://github.com/redhat-developer/podman-desktop-demo/blob/main/primary-podify-demo/backend/Dockerfile[here, window="_blank"].
+
+== Next Steps
+
+Fantastic! We've built the container image for the Python web application, and pulled the Redis image for the cache. In the next tutorial, we'll start the containers and test the web application.