Flush out the image build and add lots of explanatory comments

Author: mikesir87

Dockerfile

@@ -1,11 +1,53 @@
-FROM node:20-alpine AS base
+###################################################
+# Stage: base
+# 
+# This base stage ensures all other stages are using the same base image
+# and provides common configuration for all stages, such as the working dir.
+###################################################
+FROM node:20 AS base
 WORKDIR /usr/local/app
 
+###################################################
+# Stage: dev
+#
+# This stage is used for local development. It is expected that the files
+# are mounted into the container at runtime, hence there are no COPY
+# statements. The default CMD will install the yarn dependencies and then
+# start the development server.
+#
+# This stage is the specified in the compose.yaml file (see the target field).
+###################################################
 FROM base AS dev
 CMD ["yarn", "dev"]
 
+###################################################
+# Stage: client-build
+#
+# This stage builds the client application, producing static HTML, CSS, and
+# JS files that can be served by the backend.
+#
+# This build seeks to optimize the build cache as much as possible by
+# installing the dependencies before copying in the main source code.
+###################################################
+FROM base AS client-build
+COPY client/package.json client/yarn.lock ./
+RUN --mount=type=cache,id=yarn,target=/root/.yarn yarn install
+COPY client/.eslintrc.cjs client/index.html client/vite.config.js ./
+COPY client/public ./public
+COPY client/src ./src
+RUN yarn build
+
+###################################################
+# Stage: final
+#
+# This stage is intended to be the final "production" image. It sets up the
+# backend and copies the built client application from the client-build stage.
+###################################################
 FROM base AS final
-COPY package.json yarn.lock ./
-RUN yarn install --production
-COPY . .
+ENV NODE_ENV=production
+COPY backend/package.json backend/yarn.lock ./
+RUN --mount=type=cache,id=yarn,target=/root/.yarn yarn install --production --frozen-lockfile
+COPY backend/src ./src
+COPY --from=client-build /usr/local/app/dist ./src/static
+EXPOSE 3000
 CMD ["node", "src/index.js"]

compose.yml

@@ -1,4 +1,42 @@
+###################################################
+# This Compose file provides the development environment for the todo app.
+# 
+# Seeing the final version of the application bundles the frontend with the
+# backend, we are able to "simulate" that by using a proxy to route requests
+# to the appropriate service. All requests to /api will be routed to the 
+# backend while all other requests will be sent to the client service. While
+# there is some overlap in the routing rules, the proxy determines the service
+# based on the most specific rule.
+#
+# To support easier debugging and troubleshooting, phpMyAdmin is also included
+# to provide a web interface to the MySQL database.
+###################################################
+
+###################################################
+# Services
+#
+# The services define the individual components of our application stack.
+# For each service, a separate container will be launched.
+###################################################
 services:
+
+  ###################################################
+  # Service: proxy
+  #
+  # This service is a reverse proxy that will route requests to the appropriate
+  # service. Think of it like a HTTP router or a load balancer. It simply 
+  # forwards requests and allows us to simulate the final version of the 
+  # application where the frontend and backend are bundled together. We can 
+  # also use it to route requests to phpMyAdmin, which won't be accessible at 
+  # localhost, but at db.localhost.
+  #
+  # The image for this service comes directly from Docker Hub and is a Docker
+  # Official Image. Since Traefik can be configured in a variety of ways, we
+  # configure it here to watch the Docker events for new containers and to use
+  # their labels for configuration. That's why the Docker socket is mounted.
+  #
+  # We also expose port 80 to connect to the proxy from the host machine.
+  ###################################################
   proxy:
     image: traefik:v2.11
     command: --providers.docker
@@ -7,14 +45,29 @@ services:
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
 
+  ###################################################
+  # Service: backend
+  # 
+  # This service is the Node.js server that provides the API for the app.
+  # When the container starts, it will use the image that results
+  # from building the Dockerfile, targeting the dev stage.
+  #
+  # The code is mounted into the container, allowing the backend to be 
+  # automatically reloaded when code changes are made (thanks to nodemon).
+  #
+  # The environment variables configure the application to connect to the
+  # database, which is also configured in this Compose file. We obviously
+  # wouldn't hard-code these values in a non-production environment. But, in
+  # dev, these values are fine.
+  #
+  # Finally, the labels are used to configure Traefik (the reverse proxy) with
+  # the appropriate routing rules. In this case, all requests to localhost/api/*
+  # will be forwarded to this service's port 3000. 
+  ###################################################
   backend:
     build:
       context: ./
       target: dev
-    depends_on:
-      - mysql
-    ports:
-      - 3000:3000
     volumes:
       - ./backend:/usr/local/app
     environment:
@@ -26,6 +79,20 @@ services:
       traefik.http.routers.backend.rule: Host(`localhost`) && PathPrefix(`/api`)
       traefik.http.services.backend.loadbalancer.server.port: 3000
 
+  ###################################################
+  # Service: client
+  #
+  # The client service is the React app that provides the frontend for the app.
+  # When the container starts, it will use the image that results from building
+  # the Dockerfile, targeting the dev stage.
+  #
+  # The code is mounted into the container, allowing the client to be automatically
+  # reloaded when code changes are made (thanks to vite).
+  # 
+  # The labels are used to configure Traefik (the reverse proxy) with the 
+  # appropriate routing rules. In this case, all requests to localhost will be
+  # forwarded to this service's port 5173.
+  ###################################################
   client:
     build:
       context: ./
@@ -36,6 +103,23 @@ services:
       traefik.http.routers.client.rule: Host(`localhost`)
       traefik.http.services.client.loadbalancer.server.port: 5173
 
+
+  ###################################################
+  # Service: mysql
+  #
+  # The MySQL service is used to provide the database for the application.
+  # The image for this service comes directly from Docker Hub and is a Docker 
+  # Official Image.
+  
+  # The data is persisted in a volume named todo-mysql-data. Using a volume 
+  # allows us to take down the services without losing the data. When we start
+  # the services again, the data will still be there (assuming we didn't delete
+  # the volume, of course!).
+  #
+  # The environment variables configure the root password and the name of the
+  # database to create. Since these are used only for local development, it's
+  # ok to hard-code them here.
+  ###################################################
   mysql:
     image: mysql:8.0
     volumes:
@@ -44,6 +128,21 @@ services:
       MYSQL_ROOT_PASSWORD: secret
       MYSQL_DATABASE: todos
 
+  ###################################################
+  # Service: phpmyadmin
+  #
+  # This service provides a web interface to the MySQL database. It's useful
+  # for debugging and troubleshooting data, schemas, and more. The image for 
+  # this service comes directly from Docker Hub and is a Docker Official Image.
+  #
+  # The environment variables configure the connection to the database and 
+  # provide the default credentials, letting us immediately open the interface
+  # without needing to log in.
+  #
+  # The labels are used to configure Traefik (the reverse proxy) with the
+  # routing rules. In this case, all requests to db.localhost will be forwarded
+  # to this service's port 80.
+  ###################################################
   phpmyadmin:
     image: phpmyadmin/phpmyadmin
     environment:
@@ -54,5 +153,12 @@ services:
       traefik.http.routers.phpmyadmin.rule: Host(`db.localhost`)
       traefik.http.services.phpmyadmin.loadbalancer.server.port: 80
 
+###################################################
+# Volumes
+#
+# For this application stack, we only have one volume. It's used to persist the
+# data for the MySQL service. We are only going to use the default values,
+# hence the lack of any configuration for the volume.
+###################################################
 volumes:
   todo-mysql-data: