From 03610d874e3d860549fd14c84a3bd37ab1b9a67a Mon Sep 17 00:00:00 2001 From: MoritzWeber Date: Tue, 4 Jun 2024 11:14:51 +0200 Subject: [PATCH] docs: Add new deployment strategy by pulling images from GitHub To simplify the first deployment, this commit adds a new option, which pulls management portal and session images from GitHub. Local image building is no longer required and therefore speeds up the deployment time. --- Makefile | 52 +++++++++++++----------- README.md | 35 ++++++++++++---- docs/docs/development/index.md | 2 +- docs/docs/development/troubleshooting.md | 28 +++++++++++++ docs/mkdocs.yml | 1 + 5 files changed, 85 insertions(+), 33 deletions(-) create mode 100644 docs/docs/development/troubleshooting.md diff --git a/Makefile b/Makefile index 56439ebe7..e830b5fdf 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 02b6e4a6e..0f843ba7e 100644 --- a/README.md +++ b/README.md @@ -84,9 +84,7 @@ 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: @@ -94,20 +92,38 @@ When you have all that installed you can do the following: 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) + +> [!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 @@ -115,6 +131,7 @@ Then, choose one of the three options and run the corresponding command: ``` 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: diff --git a/docs/docs/development/index.md b/docs/docs/development/index.md index 976f5d9b2..5aa57c0b2 100644 --- a/docs/docs/development/index.md +++ b/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 diff --git a/docs/docs/development/troubleshooting.md b/docs/docs/development/troubleshooting.md new file mode 100644 index 000000000..c638a592e --- /dev/null +++ b/docs/docs/development/troubleshooting.md @@ -0,0 +1,28 @@ + + +# 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: + + +- 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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 43fdb60b2..e403214ed 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -116,6 +116,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