feat: Add comments to .gitlab-ci.yml and Dockerfile

.gitlab-ci.yml

@@ -12,8 +12,12 @@ variables:
   MIX_ENV: "test"
   DOCKER_TLS_CERTDIR: "/certs"
   DOCKER_HOST: tcp://docker:2376
+  # fetch & clean the repo rather than completely cloning (faster)
   GIT_STRATEGY: fetch
 
+# Dependency stages-- fetch these first so that we can cache them and reuse them
+#   across jobs and pipelines. Note that elixir deps need to go first, because
+#   we need the phoenix and phoenix_html hex packages to install their JS.
 fetch_application_dependencies:
   stage: application_dependencies
   image: "elixir:1.10"
@@ -29,6 +33,7 @@ fetch_application_dependencies:
     - mix local.rebar --force
     - mix deps.get
     - mix deps.compile
+  # Make results available to other jobs
   artifacts:
     paths:
       - deps/phoenix
@@ -51,12 +56,15 @@ fetch_asset_dependencies:
       - apps/app/assets/node_modules/
   script:
     - cd apps/app/assets/ && npm install
+  # Make results available to other jobs
   artifacts:
     paths:
       - apps/app/assets/node_modules
     exclude:
       - apps/app/assets/node_modules
 
+# Test stage. Runs various tests and speculatively builds docker image in
+#   parallel, in case the build passes.
 test:
   stage: test
   needs:
@@ -93,11 +101,16 @@ build_image_for_commit:
   script:
     - docker login "https://${CI_REGISTRY}" -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD
     - docker pull $CI_REGISTRY_IMAGE:latest || true
+    # This enables fast parallel builds
     - export DOCKER_BUILDKIT=1
     - docker build --cache-from $CI_REGISTRY_IMAGE:latest -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --build-arg BUILDKIT_INLINE_CACHE=1 .
+    # Push the commit SHA tagged version to registry. We will later choose to tag that as stable
+    #   if everything passes.
     - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+    # This copies the elixir build artifacts for deps and app so that we can cache them
     - docker cp `docker create $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA`:/root/app/_build/prod _build
 
+# If tests pass, tag the commit and update package versions
 deploy_to_tags:
   stage: deploy_tags
   needs: ['test']
@@ -118,6 +131,8 @@ deploy_to_tags:
     reports:
       dotenv: build.env
 
+# If the tests passed, we take the image for this SHA and tag it with the version
+#   and latest, so we can signal that it is ready for prod
 deploy_commit_image_to_tag:
   stage: deploy
   needs:

Dockerfile

@@ -17,6 +17,8 @@ ENV PORT=4000
 
 WORKDIR /root/app
 
+# We load these things one by one so that we can load the deps first and
+#   cache those layers, before we do the app build itself
 ADD ./config /root/app/config
 ADD ./mix.exs /root/app/
 ADD ./mix.lock /root/app/
@@ -27,14 +29,15 @@ ADD ./apps/core/mix.exs /root/app/apps/core/
 ADD ./deps /root/app/deps
 ADD ./_build /root/app/_build
 RUN mix deps.get
+RUN mix deps.compile
 
-ADD ./script /root/app/script
 ADD ./apps /root/app/apps
 
-RUN MAKE=cmake mix compile
+# Leave off here so that we can built assets and compile the elixir app in parallel
 
 FROM node:15.0
 
+# Build assets in a node container
 WORKDIR /root/app/apps/app/assets/
 ADD ./apps/app/assets/node_modules /root/app/apps/app/assets/node_modules
 COPY --from=0 /root/app/ /root/app/
@@ -43,8 +46,12 @@ RUN npm run deploy
 
 FROM elixir1
 
-COPY --from=1 /root/app/apps/app/priv/static/ /root/app/apps/app/priv/static
+# Resume compilation of the elixir app
+ADD ./script /root/app/script
+RUN MAKE=cmake mix compile
 
+# Copy in the built assets & fingerprint them
+COPY --from=1 /root/app/apps/app/priv/static/ /root/app/apps/app/priv/static
 RUN mix phx.digest
 
 CMD ["mix", "phx.server"]