Merge pull request #1601 from DSD-DBS/improve-quick-start

docs: Add new deployment strategy by pulling images from GitHub

Makefile

@@ -10,8 +10,10 @@ SESSION_NAMESPACE = collab-sessions
 K3D_REGISTRY_PORT = 12345
 K3D_REGISTRY_NAME = myregistry.localhost
 
-DOCKER_REGISTRY ?= k3d-$(K3D_REGISTRY_NAME):$(K3D_REGISTRY_PORT)
-CAPELLACOLLAB_SESSIONS_REGISTRY ?= $(DOCKER_REGISTRY)
+DOCKER_REGISTRY ?= k3d-$(K3D_REGISTRY_NAME):$(K3D_REGISTRY_PORT)/capella/collab
+CAPELLACOLLAB_SESSIONS_REGISTRY ?= k3d-$(K3D_REGISTRY_NAME):$(K3D_REGISTRY_PORT)
+
+DOCKER_TAG ?= $$(git describe --tags --abbrev=0)
 
 # List of Capella versions, e.g.: `5.0.0 5.2.0 6.0.0`
 CAPELLA_VERSIONS ?= 6.0.0
@@ -37,29 +39,29 @@ include .env
 SHELL = /bin/bash
 .SHELLFLAGS = -euo pipefail -c
 
-build: backend frontend docs guacamole jupyter session-preparation
+build: backend frontend docs guacamole session-preparation
 
-backend: IMAGE=capella/collab/backend
 backend:
 	python backend/generate_git_archival.py;
-	docker build -t $(IMAGE) -t $(DOCKER_REGISTRY)/$(IMAGE) backend
-	docker push $(DOCKER_REGISTRY)/$(IMAGE)
+	docker build -t $@ -t $(DOCKER_REGISTRY)/$@ -t $(DOCKER_REGISTRY)/$@:$(DOCKER_TAG) backend
+	docker push -a $(DOCKER_REGISTRY)/$@
 
-frontend: IMAGE=capella/collab/frontend
 frontend:
 	python frontend/fetch-version.py
-	docker build -t $(IMAGE) -t $(DOCKER_REGISTRY)/$(IMAGE) frontend
-	docker push $(DOCKER_REGISTRY)/$(IMAGE)
+	docker build -t $@ -t $(DOCKER_REGISTRY)/$@ -t $(DOCKER_REGISTRY)/$@:$(DOCKER_TAG) frontend
+	docker push -a $(DOCKER_REGISTRY)/$@
 
-guacamole: IMAGE=capella/collab/guacamole
 guacamole:
-	docker build -t $(IMAGE) -t $(DOCKER_REGISTRY)/$(IMAGE) images/guacamole
-	docker push $(DOCKER_REGISTRY)/$(IMAGE)
+	docker build -t $@ -t $(DOCKER_REGISTRY)/$@ -t $(DOCKER_REGISTRY)/$@:$(DOCKER_TAG) images/guacamole
+	docker push -a $(DOCKER_REGISTRY)/$@
 
-session-preparation: IMAGE=capella/collab/session-preparation
 session-preparation:
-	docker build -t $(IMAGE) -t $(DOCKER_REGISTRY)/$(IMAGE) images/session-preparation
-	docker push $(DOCKER_REGISTRY)/$(IMAGE)
+	docker build -t $@ -t $(DOCKER_REGISTRY)/$@ -t $(DOCKER_REGISTRY)/$@:$(DOCKER_TAG) images/session-preparation
+	docker push -a $(DOCKER_REGISTRY)/$@
+
+docs:
+	docker build -t $@ -t $(DOCKER_REGISTRY)/$@ -t $(DOCKER_REGISTRY)/$@:$(DOCKER_TAG) docs
+	docker push -a $(DOCKER_REGISTRY)/$@
 
 capella:
 	$(CAPELLA_DOCKERIMAGES) CAPELLA_VERSIONS="$(CAPELLA_VERSIONS)" capella/remote
@@ -70,14 +72,10 @@ t4c-client:
 jupyter:
 	$(CAPELLA_DOCKERIMAGES) jupyter-notebook
 
-docs:
-	docker build -t capella/collab/docs -t $(DOCKER_REGISTRY)/capella/collab/docs docs
-	docker push $(DOCKER_REGISTRY)/capella/collab/docs
-
-deploy: build capella helm-deploy rollout open
+deploy: build jupyter capella helm-deploy rollout open
 
 # Deploy with full T4C client support:
-deploy-t4c: build t4c-client helm-deploy rollout open
+deploy-t4c: build jupyter t4c-client helm-deploy rollout open
 
 deploy-without-build: helm-deploy rollout open
 
@@ -92,9 +90,9 @@ helm-deploy:
 		--namespace $(NAMESPACE) \
 		--values helm/values.yaml \
 		$$(test -f secrets.yaml && echo "--values secrets.yaml") \
-		--set docker.registry.internal=$(DOCKER_REGISTRY)/capella/collab \
+		--set docker.registry.internal=$(DOCKER_REGISTRY) \
 		--set docker.registry.sessions=$(CAPELLACOLLAB_SESSIONS_REGISTRY) \
-		--set docker.tag=latest \
+		--set docker.tag=$(DOCKER_TAG) \
 		--set mocks.oauth=True \
 		--set development=$(DEVELOPMENT_MODE) \
 		--set cluster.ingressClassName=traefik \
@@ -173,6 +171,14 @@ provision-guacamole:
 	kubectl exec -i --context k3d-$(CLUSTER_NAME) --namespace $(NAMESPACE) deployment/$(RELEASE)-guacamole-postgres -- psql -U guacamole guacamole
 	@echo "Guacamole database initialized sucessfully.";
 
+reach-registry:
+	@r=0;
+	curl http://k3d-myregistry.localhost:12345/v2/ || r=$$?
+	if [ $$r -ne 0 ]; then
+		echo "The registry is not reachable. Possible solutions are described in our documentation: "
+		echo "https://dsd-dbs.github.io/capella-collab-manager/development/troubleshooting/"
+		exit 1
+	fi
 
 dev:
 	$(MAKE) -j5 dev-frontend dev-backend dev-oauth-mock dev-docs dev-storybook

README.md

@@ -84,37 +84,54 @@ To deploy the application you need:
 
 If you'd like to run it locally, these tools are additionally required:
 
-- [k3d](https://k3d.io/) - a lightweight k8s cluster simulator
-- On some systems: `nss-myhostname` to access the local container registry (on
-  Ubuntu you can get it via `sudo apt install libnss-myhostname`)
+- [k3d](https://k3d.io/) - a lightweight k8s cluster
 
 When you have all that installed you can do the following:
 
 ```zsh
 git clone --recurse-submodules https://github.com/DSD-DBS/capella-collab-manager.git
 cd capella-collab-manager
 
-# Create a Local k3d Cluster
-make create-cluster
+# Create a local k3d cluster and test the registry reachability
+make create-cluster reach-registry
 ```
 
-Then, choose one of the three options and run the corresponding command:
+Then, choose one of the four options and run the corresponding command. The
+options can be changed at any time later:
 
-1. Fetch Capella images from Github (without initial TeamForCapella support)
+<!-- prettier-ignore -->
+> [!NOTE]
+> Currently, we only provide amd64 images. If you want to run the
+> application on arm64, you need to build the images yourself (option 3 or 4).
+
+1. Fetch management portal and session images from Github (without
+   TeamForCapella support). This option is recommended for the first
+   deployment.
+
+   ```zsh
+   export DOCKER_REGISTRY=ghcr.io/dsd-dbs/capella-collab-manager
+   export CAPELLACOLLAB_SESSIONS_REGISTRY=ghcr.io/dsd-dbs/capella-dockerimages
+   DEVELOPMENT_MODE=1 make helm-deploy open
+   ```
+
+1. Build management portal images and fetch session images from Github (without
+   initial TeamForCapella support)
 
    ```zsh
    export CAPELLACOLLAB_SESSIONS_REGISTRY=ghcr.io/dsd-dbs/capella-dockerimages
    DEVELOPMENT_MODE=1 make build helm-deploy open rollout
    ```
 
-2. Build Capella images locally (without initial TeamForCapella support) \
+1. Build management portal and session images locally (without initial
+   TeamForCapella support) \
    To reduce the build time, the default configutation only builds images for
    Capella 6.0.0. If you want to build more images for different versions, set
    the environment variable `CAPELLA_VERSIONS` with a space-separated list of
    semantic Capella versions.
 
    ```
    export CAPELLA_VERSIONS="6.0.0 6.1.0"
+   export BUILD_ARCHITECTURE=amd64 # or arm64
    ```
 
    Then, run the following command:
@@ -123,7 +140,7 @@ Then, choose one of the three options and run the corresponding command:
    DEVELOPMENT_MODE=1 make deploy
    ```
 
-3. Build Capella and TeamForCapella images locally (with initial TeamForCapella
+1. Build Capella and TeamForCapella images locally (with initial TeamForCapella
    support)
 
    Read and execute the preparation in the Capella Docker images documentation:

docs/docs/development/index.md

@@ -43,7 +43,7 @@ The backend uses various configuration settings. You can find them in the
 `backend/config` directory. A `config.yaml` with default values will be
 generated the first time you run the application.
 
-_Hint_: If you already have the k8d cluster running and if you have the
+_Hint_: If you already have the k3d cluster running and if you have the
 application deployed, then no configuration values need to be adjusted.
 
 ### Getting Started

docs/docs/development/troubleshooting.md

@@ -0,0 +1,28 @@
+<!--
+ ~ SPDX-FileCopyrightText: Copyright DB InfraGO AG and contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# Troubleshooting
+
+## The `k3d` Registry is Unreachable
+
+If the k3d registry is unreachable, i.e. the `make reach-registry` command
+fails with errors like "Could not resolve host", `k3d-myregistry.localhost`
+isn't resolved properly to `127.0.0.1`. To resolve this, you can try the
+following options:
+
+<!-- prettier-ignore -->
+- On Debian/Ubuntu based systems, you can install nss-myhostname.
+  `nss-myhostname` resolves all subdomains of localhost to localhost:
+   ```sh
+   sudo apt install libnss-myhostname
+   ```
+
+- Add the following line to the `/etc/hosts` on the host machine:
+   ```
+   127.0.0.1 k3d-myregistry.localhost
+   ```
+
+After applying the steps, verify that the registry is reachable by running
+`make reach-registry` again.

docs/mkdocs.yml

@@ -117,6 +117,7 @@ nav:
           - Measure Resource Usage: development/k8s/resources.md
       - Documentation: development/docs.md
       - Pull Request Acceptance Criteria: development/pull_requests.md
+      - Troubleshooting: development/troubleshooting.md
 
 repo_url: https://github.com/DSD-DBS/capella-collab-manager
 edit_uri: edit/master/docs/docs