system/deployment/Building-Container-Images.md

+## Building container images
+
+This page outlines the process of building container images on the `builder` VM and sending them to the VM actually running an RDMS instance without using a container registry.
+
+As `builder@builder.rd.ruhr-uni-bochum.de`:
+
+```bash
+cd "${HOME}/rdms"
+
+# Fetch latest changes from Gitlab server
+git fetch
+
+# Checkout git branch from which to build our image
+git checkout some-feature-branch
+
+# Verify that there are no changes that have not been committed to the git branch we just checked out
+git status
+
+# Get latest changes from git repo
+git pull
+
+# Note: Do *not* apply any local changes that are not committed/documented in the git branch you checked out!
+
+# Only generate the DOCKER_IMAGE_TAG variable once *after* applying all your changes, then copy/reuse the generated value when issuing commands later on
+export DOCKER_IMAGE_TAG="$(git describe --long --tags)_$(date --utc --iso-8601=seconds | sed 's|\+00:00$|UTC|g;s|:|-|g')"
+
+# Build the actual container images
+docker compose -f docker-compose.yml build --pull --no-cache
+
+# Show the generated DOCKER_IMAGE_TAG for copying/reusing on other machines
+echo "DOCKER_IMAGE_TAG: ${DOCKER_IMAGE_TAG}"
+# This should print something like the following line:
+# DOCKER_IMAGE_TAG v1.0-beta1-1-g6113168_2023-11-06T15-03-15UTC
+
+# Tag the new "latest" images on the builder VM with our generated DOCKER_IMAGE_TAG
+docker image tag "rdms-app:latest" "rdms-app:${DOCKER_IMAGE_TAG}"
+docker image tag "rdms-web:latest" "rdms-web:${DOCKER_IMAGE_TAG}"
+docker image tag "rdms-workers:latest" "rdms-workers:${DOCKER_IMAGE_TAG}" 
+```
+
+As normal user on your own laptop / office workstation:
+
+```bash
+# This should be set to the same value/string that was printed on the builder VM
+export DOCKER_IMAGE_TAG="v1.0-beta1-1-g6113168_2023-11-06T15-03-15UTC"
+
+# Copy the new tagged images from the builder VM over to the RDMS VM
+ssh builder@builder.rd.rub.de "docker image save rdms-app:${DOCKER_IMAGE_TAG} rdms-web:${DOCKER_IMAGE_TAG} rdms-workers:${DOCKER_IMAGE_TAG}" | dd status=progress bs=1M | ssh rdms@rdms-demo.rd.rub.de "docker load"
+```
+
+As `rdms@rdms-demo.rd.ruhr-uni-bochum.de`:
+
+```bash
+cd "${HOME}/rdms"
+
+# Stop the running docker containers (usually with the old "latest" images
+docker compose -f docker-compose.yml down
+
+# tag new images as "latest"
+# This should be set to the same value/string that was printed on the builder VM
+export DOCKER_IMAGE_TAG="v1.0-beta1-1-g6113168_2023-11-06T15-03-15UTC"
+docker image tag "rdms-app:${DOCKER_IMAGE_TAG}" "rdms-app:latest"
+docker image tag "rdms-web:${DOCKER_IMAGE_TAG}" "rdms-web:latest"
+docker image tag "rdms-workers:${DOCKER_IMAGE_TAG}" "rdms-workers:latest"
+
+# Start docker containers again with new "latest" images
+docker compose -f docker-compose.yml up -d
+```
\ No newline at end of file