Hinweise zum Programmierbeispiel

Diese Datei ist in Markdown geschrieben und kann mit <Strg><Shift>v in Visual Studio Code leicht gelesen werden. Dazu wird die Extension Markdown Preview Mermaid Support empfohlen, um UML-Diagramme in der Syntax von Mermaid (wie bei PlantUML) visualisieren zu können. Durch den Aufruf npm run readme2html wird diese Markdown-Datei in eine HTML-Datei im Verzeichnis .extras\doc konvertiert.

Näheres zu Markdown gibt es z.B. bei Markdown Guide

Nur in den ersten beiden Vorlesungswochen kann es Unterstützung bei Installationsproblemen geben.

Inhalt

Hinweise zum Programmierbeispiel

Download- und ggf. Upload Geschwindigkeit

In einem Webbrowser kann man z.B. mit der URL https://speed.cloudflare.com die Download- und die Upload-Geschwindigkeit testen.

Alternativ kann man durch das Kommando fast in einer Powershell die aktuelle Download-Geschwindigkeit ermitteln. Mit der zusätzlichen Option --upload kann zusätzlich die aktuelle Upload-Geschwindigkeit ermittelt werden.

Vorbereitung der Installation

Das Beispiel nicht in einem Pfad mit Leerzeichen installieren. Viele Javascript-Bibliotheken werden unter Linux entwickelt und dort benutzt man keine Leerzeichen in Pfaden. Ebenso würde ich das Beispiel nicht auf dem Desktop auspacken bzw. installieren.
Bei GitHub oder GitLab registrieren, falls man dort noch nicht registriert ist.

ES Modules (= ESM)

ESM ist die gängige Abkürzung für ES Modules, so dass man import und export statt require() aus CommonJS verwenden kann. Die Unterstützung von ESM wurde in Node ab Version 12 begonnen. Außerdem ist es wichtig, das man beim Umstieg auf ESM auch die Unterstützung in ts-node und ts-jest beachtet.

Wenn man ESM verwendet, muss man die eigenen Module z.B. folgendermaßen importieren:

    import { myFunc } from './foo.js';
    import { myClass } from './bar/index.js';

Außerdem gibt es ab Node 17.1 das Node Protocol für den Import von Builtin Modules, z.B.:

    import { resolve } from 'node:path';

Gute Literatur zu ESM gibt es bei:

Unterstützung für ESM ist notwendig in:

Node
TypeScript
ts-node
ts-jest: versteht noch nicht die Datei-Endung .mts und beim Import .mjs
VS Code
Node innerhalb von Jenkins

DB-Server und DB-Browser

DB-Server

❗ Vor dem 1. Start von PostgreSQL muss man die Skripte create-db-buch.sql und create-schema-buch.sql aus dem Verzeichnis .extras\db\postgres\sql nach C:\Zimmermann\volumes\postgres\sql kopieren und die Anleitung ausführen. Danach kopiert man die CSV-Dateien aus dem Verzeichnis .extras\postgres\csv nach C:\Zimmermann\volumes\postgres\csv\buch.

❗ Vor dem 1. Start von MySQL muss man das Skript create-db-buch.sql aus dem Projektverzeichnis .extras\db\mysql\sql nachC:\Zimmermann\volumes\mysql\sql kopieren und die Anleitung ausführen. Danach kopiert man die CSV-Dateien aus dem Verzeichnis .extras\db\mysql\csv nach C:\Zimmermann\volumes\mysql\csv\buch.

Vor dem Start des Appservers muss man den DB-Server und ggf. den DB-Browser starten. Falls man PostgreSQL oder MySQL und nicht SQLite als "Embedded Database" nutzt:

    # PostgreSQL mit pgAdmin
    cd .\extras\compose\postgres
    docker compose up

    # alternativ: MySQL mit phpMyAdmin:
    cd .\extras\compose\mysql
    docker compose up

Der DB-Server wird zusammen mit dem DB-Browser als Container gestartet. Sie sind als Service in der jeweiligen Datei compose.yml unter Verwendung der Docker-Images konfiguriert:

Image postgres für PostgreSQL
Image dpage/pgadmin4 für pgAdmin
Image mysql für MySQL
Image phpmyadmin/phpmyadmin für phpMyAdmin

Jetzt läuft der DB-Server mit folgender Konfiguration:

Rechnername localhost aus Windows-Sicht
Default-Port 5432 bei PostgreSQL bzw. 3306 bei MySQL
Datenbankname buch
Administrations-User postgres bei PostgreSQL bzw. root bei MySQL
Passwort p für den jeweiligen Administrations-User

pgAdmin

pgadmin kann zur Administration von PostgreSQL verwendet werden und ist durch Docker Compose über ein virtuelles Netzwerk mit dem Docker-Container des DB-Servers verbunden. Deshalb muss beim Verbinden mit dem DB-Server der virtuelle Rechnername postgres statt localhost verwendet werden. pgadmin kann man mit einem Webbrowser und der URL http://localhost:8888 aufrufen. Die Emailadresse pgadmin@acme.com und das Passwort p sind voreingestellt. pgadmin ist übrigens mit Chromium implementiert.

Beim 1. Einloggen konfiguriert man einen Server-Eintrag mit z.B. dem Namen localhost und verwendet folgende Werte:

Host: postgres (virtueller Rechnername des DB-Servers im Docker-Netzwerk. BEACHTE: localhost ist im virtuellen Netzwerk der Name des pgadmin-Containers selbst !!!)
Port: 5432 (Defaultwert)
Username: postgres (Superuser beim DB-Server)
Password: p

Es empfiehlt sich, das Passwort abzuspeichern, damit man es künftig nicht jedes Mal beim Einloggen eingeben muss.

phpMyAdmin

phpMyAdmin kann zur Administration von MySQL verwendet werden. phpMyAdmin ist durch Docker Compose über ein virtuelles Netzwerk mit dem Docker-Container des DB-Servers verbunden. Deshalb muss beim Verbinden mit dem DB-Server auch der virtuelle Rechnername mysql statt localhost verwendet werden. Man ruft phpMyAdmin mit einem Webbrowser und der URL http://localhost:8889 auf. Zum Einloggen verwendet folgende Werte:

Server: mysql (virtueller Rechnername des DB-Servers im Docker-Netzwerk. BEACHTE: localhost ist im virtuellen Netzwerk der Name des phpMyAdmin-Containers selbst !!!)
Benutzername: root (Superuser beim DB-Server)
Password: p

Node Best Practices

Sehr empfehlenswert ist https://github.com/goldbergyoni/nodebestpractices

Lokaler Appserver mit Nest und dem Watch-Modus

Durch npm run dev wird der Appserver im Watch-Modus für die Entwicklung gestartet, d.h. bei Code-Änderungen wird der Server automatisch neu gestartet. Durch die Option --builder swc beim Node-Skript swc in der Datei package.json wird swc (= speedy web compiler) anstatt des TypeScript-Compilers tsc verwendet. swc ist in Rust implementiert und bis zu 20x schneller als tsc. Defaultmäßig arbeitet swc allerdings ohne Typprüfungen. Beim Node-Skript swc:check wird zusätzlich die Option --type-check verwendet.

Beim Starten des Appservers wird außerdem mit TypeORM auf die Datenbank zugegriffen. Der Benutzername und das Passwort sind in der Datei src\config\db.ts auf admin und p voreingestellt. Durch die Property db.populate in src\config\resources\buch.yml wird festgelegt, ob die (Test-) DB buch neu geladen wird.

OpenAPI

Durch die Decorators @Api...() kann man OpenAPI (früher: Swagger) in den Controller-Klassen und -Methoden konfigurieren und dann in einem Webbrowser mit https://localhost:3000/swagger aufrufen. Die Swagger JSON Datei kann man mit https://localhost:3000/swagger-json abrufen.

Postman: Desktop-Anwendung und Extension für VS Code

Mit der Desktop-Applikation Postman wie auch mit der Erweiterung Postman für VS Code kann man u.a. REST-, GraphQL und gRPC-Schnittstellen interaktiv testen.

Registrieren und Installieren

Zunächst muss man sich bei https://www.postman.com registrieren und kann danach die Desktop-Application Postman von https://www.postman.com/downloads herunterladen und installieren. Die Installation erfolgt dabei im Verzeichnis ${LOCALAPPDATA}\Postman\app-VERSION, z.B. C:\Users\MeineKennung\AppData\Local\Postman\app-VERSION.

Workspace anlegen

Über die Desktop-Applikation legt man sich folgendermaßen einen Workspace an:

Den Menüpunkt Workspaces anklicken
Im Drop-Down Menü den Button Create Workspace anklicken
Danach den Button Next anklicken
Im Eingabefeld Name buch und im Eingabefeld Summary z.B. REST- und GraphQL-Requests für den Appserver.
Abschließend den Button Create anklicken.

Environments

Zunächst legt man ein Environment mit Variablen an. Dazu wählt man am linken Rand den Menüpunkt Environments, klickt auf den Button Import und wählt aus dem Verzeichnis .extras\postman die Datei buch.postman_environment.json aus. Jetzt hat man die Umgebung buch mit der Variablen base_url und dem Wert https://localhost:3000 angelegt.

Im Environment buch muss man die Variable client_secret auf den Wert setzen, der in Keycloak beim Realm acme in Clients > buch-client > Credentials bei Client Secret steht.

Collections und Folders

Als nächstes wählt man den Menüpunkt Collections aus und importiert der Reihe nach Collections aus dem Verzeichnis .extras\postman, indem man den Button Import anklickt. Collections sind zusammengehörige Gruppierungen von Requests und können zur besseren Strukturierung in Folder unterteilt werden. Beispielsweise gibt es die Collection REST mit untergeordneten Folder, wie z.B. Suche mit ID und Neuanlegen. Im Folder Suche mit ID gibt es dann z.B. den Eintrag GET vorhandene ID 1, um einen GET-Request mit dem Pfadparameter :id und dem Wert 1 abzusetzen.

Eine neue Collection legt man mit dem Button + an und einen untergeordneten Folder mit dem Overflow-Menü sowie dem Menüpunkt Add folder.

Requests

Im Overflow-Menü eines Folders oder einer Collection kann man durch den Menüpunkt Add request einen neuen Eintrag für Requests erstellen, wobei man dann z.B. folgendes festlegt:

Bezeichnung des Eintrags
GET, POST, PUT, PATCH, DELETE
URL mit ggf. Pfadparameter, z.B. :id
Im Karteireiter Params sieht man dann die Pfadparameter und kann auch Query-Parameter spezifizieren.
Im Karteireiter Headers sieht man voreingestellte Request-Header und kann auch zusätzliche eintragen, z.B. den Header Content-Type und als zugehörigen Wert application/hal+json.
Im Karteireiter Body kann man z.B. JSON-Daten für einen POST-Request oder Daten für GraphQL-Queries oder -Mutations eintragen. Dazu wählt man dann unterhalb von Body den Radiobutton raw mit JSON aus, wenn man einen POST- oder PUT-Request spezifiziert bzw. den Radiobutton GraphQL für Queries oder Mutations aus.
Wenn man GraphQL-Requests spezifiziert, d.h. im Request-Body GraphQL festlegt, dann lädt Postman aufgrund der Request-URL das zugehörige GraphQL-Schema herunter, falls man die Vorbelegung Auto-fetch beibehält. Dadurch hat man Autovervollständigen beim Formulieren von Queries und Mutations.

Beachte: Wenn man gebündelte Requests von Collections oder Folders abschickt, hat man bis zu 50 "Runs" pro Monat frei.

Variable

Um bei der URL für die diversen Requests nicht ständig wiederholen zu müssen, kann man in einer Collection auch Variable definieren, indem man die Collection auswählt und dann den Karteireiter Variables, z.B. rest_url als Variablenname und https://localhost:3000/rest als zugehöriger Wert.

Tokens durch Pre-request Scripts und Authorization-Header

Wenn ein Request eine URL adressiert, für die man einen Token benötigt, so muss ein solcher Token vor dem Abschicken des Requests ermittelt werden. Dazu trägt man bei der Collection, beim Folder oder beim konkreten Request im Karteireiter Pre-request Script ein JavaScript ein, mit dem man vorab einen (Hilfs-) Request senden kann, dessen Response dann einen Token liefert. Der Request wird mit pm.sendRequest({...}, myCallback) abgeschickt.

Falls der Token im Response-Body in einem JSON-Datensatz z.B. in der Property token empfangen wird, kann man den Token in z.B. einer Variablen in der Collection puffern. Dazu liest man im Callback den Token durch res.json().token aus dem Response-Body aus und puffert ihn z.B. in einer Collection-Variablen TOKEN. Das ergibt insgesamt die Anweisung: pm.collectionVariables.set('TOKEN', res.json().token).

Unter dieser Voraussetzung kann man dann im Karteireiter Authorization bei der Collection, beim Folder oder beim Request als Type die Option Bearer Token auswählen und als Wert {{TOKEN}} eintragen. Dadurch wird der Request-Header Authorization mit dem Wert Bearer <Aktueller_Token> generiert.

Tests in Postman

Wenn man Requests einzeln oder komplett für einen Folder oder eine Collection abschickt, dann kann man in Postman den zugehörigen Response zu jedem Request überprüfen. Dazu implementiert man ein JavaScript-Skript im Karteireiter Tests. Zur Überprüfung von z.B. Statuscode, Response-Header oder Response-Body stellt Postman die Chai Assertion Library mit expect bereit. Details zu Chai findet man bei https://www.chaijs.com/api/bdd.

Erweiterung für VS Code

Seit Mai 2023 gibt es Postman auch als Erweiterung für VS Code. Damit kann man zwar (noch) nicht Workspaces, Collections, Folders und Requests anlegen, aber Requests abschicken, ohne dass man VS Code als Arbeitsumgebung verlassen muss.

REST Client als Extension

Als Alternative zu Postman kann man auch die Extension REST Client nutzen.

Tests aufrufen

Folgende Voraussetzungen müssen oder sollten erfüllt sein:

Der DB-Server muss gestartet sein.
Der Appserver muss nicht gestartet sein.

Nun kann man die Tests folgendermaßen in einer Powershell aufrufen. Dabei wird beim Skript test in package.json die Property log.default auf true gesetzt, um nicht zu detailliert zu protokollieren bzw. damit die Log-Ausgabe übersichtlich bleibt.

    npm t

Bei der Fehlersuche ist es ratsam, nur eine einzelnen Testdatei aufzurufen, z.B.:

    npm exec jest --detectOpenHandles --errorOnDeprecated `
      --forceExit --runTestsByPath '__tests__\buch\buch-GET.controller.test.ts'

Docker-Image und Docker Compose

Minimales Basis-Image

Für ein minimales Basis-Image gibt es folgende Alternativen:

Debian Bookworm slim
- ca. 250 MB
- Bookworm ist der Codename für Debian 12
- mit Node 20
Distroless
- ca. 170 MB
- auf Basis von Debian 11 (Codename Bullseye)
- ohne Shell, Package Manager, GUI, grep, sed, awk, ...
- nur 2% der Größe vom vollständigen Debian und 50 % von Alpine
- mit Node 20
- von Google
Wolfi
- ca. 110 MB
- minimales Community Linux von Chainguard
- undistro: keine volle Linux-Distribution
- nutzt den Linux-Kernel der Laufzeitumgebung, z.B. Container Runtime
- glibc als C-Bibliothek und nicht musl wie bei Alpine
- ash als Shell
- apk als Package-Format wie bei Alpine
- mit Node LTS: 18.x
- https://github.com/wolfi-dev
- https://chainguard.dev

Image erstellen

Durch eine Default-Datei Dockerfile kann man ein Docker-Image erstellen und durch ein Multi-stage Build optimieren. Eine weitverbreitete Namenskonvention für ein Docker-Image ist <registry-name>/<username>/<image-name>:<image-tag>. Ob das Dockerfile gemäß Best Practices (https://docs.docker.com/develop/develop-images/dockerfile_best-practices) erstellt wurde, kann man mit Hadolint überprüfen.

Je nach Basis-Image kann man ein Image folgendermaßen erstellen und mit Hadolint validieren:

    # Distroless (Debian Bullseye bzw. 11)
    Get-Content Dockerfile | docker run --rm --interactive hadolint/hadolint:2.12.1-beta-debian
    docker build --tag juergenzimmermann/buch:2024.04.0-distroless .

    # Debian Bookworm (12) slim
    Get-Content Dockerfile.debian | docker run --rm --interactive hadolint/hadolint:2.12.1-beta-debian
    docker build --tag juergenzimmermann/buch:2024.04.0-bookworm --file Dockerfile.bookworm .

    # Wolfi
    Get-Content Dockerfile.wolfi | docker run --rm --interactive hadolint/hadolint:2.12.1-beta-debian
    docker build --tag juergenzimmermann/buch:2024.04.0-wolfi --file Dockerfile.wolfi .

Image inspizieren

docker inspect

Mit dem Unterkommando inspect kann man die Metadaten, z.B. Labels, zu einem Image inspizieren:

    docker inspect juergenzimmermann/buch:2024.04.0-distroless
    docker inspect juergenzimmermann/buch:2024.04.0-bookworm
    docker inspect juergenzimmermann/buch:2024.04.0-wolfi

docker sbom

Mit dem Unterkommando sbom (Software Bill of Materials) von docker kann man inspizieren, welche Bestandteilen in einem Docker-Images enthalten sind, z.B. npm-Packages oder Debian-Packages.

    docker sbom juergenzimmermann/buch:2024.04.0-distroless
    docker sbom juergenzimmermann/buch:2024.04.0-bookworm
    docker sbom juergenzimmermann/buch:2024.04.0-wolfi

dive

Mit dive kann man ein Docker-Image und die einzelnen Layer inspizieren, z.B.:

    cd .extras
    # Distroless Image als Basis-Image
    .\dive.ps1
    # Debian Bookworm als Basis-Image
    .\dive.ps1 bookworm
    # Wolfi als Basis-Image
    .\dive.ps1 wolfi

Docker Compose

Mit Docker Compose und der Konfigurationsdatei compose.yml im Verzeichnis .extras\compose lässt sich der Container mit dem Basis-Image distroless (Debian Bullseye bzw. 11) folgendermaßen starten und später in einer weiteren PowerShell herunterfahren.

    cd .extras/compose

    # PowerShell fuer buch-Server mit distroless-Image zzgl. DB-Server und Mailserver
    docker compose up

    # alternativ: buch-Image mit Debian Bookworm
    docker compose -f compose.yml -f compose.bookworm.yml up

    # alternativ: buch-Image mit Wolfi
    docker compose -f compose.yml -f compose.wolfi.yml up

    # Nur zur Fehlersuche: weitere PowerShell für bash (NICHT bei distroless!)
    cd .extras\compose
    docker compose exec buch bash
        id
        env
        exit

    # Fehlersuche im Netzwerk:
    docker compose -f compose.busybox.yml up
    docker compose exec busybox sh
        nslookup postgres
        exit

    # 2. Powershell: buch-Server einschl. DB-Server und Mailserver herunterfahren
    cd .extras/compose
    docker compose down

Statische Codeanalyse und Formattierer

Prettier

Prettier ist ein Formatierer, der durch .prettierrc.yml (rc = run command) konfiguriert und durch folgendes npm-Skript ausgeführt wird:

    npm run prettier

ESLint

ESLint wird durch .eslintrc.yml (rc = run command) konfiguriert und durch folgendes npm-Skript ausgeführt:

    npm run eslint

SonarQube

Für eine statische Codeanalyse durch SonarQube muss zunächst der SonarQube-Server mit Docker Compose als Docker-Container gestartet werden:

    cd .extras\compose\sonarqube
    docker compose up

Wenn der Server zum ersten Mal gestartet wird, ruft man in einem Webbrowser die URL http://localhost:9000 auf. In der Startseite muss man sich einloggen und verwendet dazu als Loginname admin und ebenso als Password admin. Danach wird man weitergeleitet, um das initiale Passwort zu ändern.

Nun wählt man in der Webseite rechts oben das Profil über MyAccount aus und klickt auf den Karteireiter Security. Im Abschnitt Generate Tokens macht man nun die folgende Eingaben:

Name: z.B. Software Engineering
Type: Global Analysis Token auswählen
Expires in: z.B. 90 days auswählen

Abschließend klickt man auf den Button Generate und trägt den generierten Token in der Datei .env für die Umgebungsvariable SONAR_TOKEN ein, damit der Token im Skript scripts\sonar-scanner.js verwendet werden kann.

Nachdem der Server gestartet ist, wird der SonarQube-Scanner in einer zweiten PowerShell mit npm run sonar gestartet. Das Resultat kann dann in der Webseite des zuvor gestarteten Servers über die URL http://localhost:9000 inspiziert werden. Falls es dabei zu einem Fehler kommt, kann man auch direkt C:\Users\<MY__USER>\.sonar\native-sonar-scanner\sonar-scanner-5.0.1.3006-windows\bin\sonar-scanner aufrufen.

Abschließend wird der oben gestartete Server heruntergefahren.

    cd .extras\compose\sonarqube
    docker compose down

Madge

Mit Madge kann man zyklische Abhängigkeiten auflisten lassen: npm run madge. Mit npm run madge:dep kann man sämtliche Abhängigkeiten in einer SVG-Datei dependencies.svg visualisieren.

type-coverage

Mit type-coverage kann man ermitteln, wo im TypeScript-Code any verwendet wurde:

    npm run type-coverage

Sicherheitslücken

npm audit

Mit dem Unterkommando audit von npm kann man npm_modules auf Sicherheitslücken analysieren. Dabei lässt man sinnvollerweise die devDependencies aus package.json weg:

    npm audit --omit dev

Docker Scout

Mit dem Unterkommando quickview von Scout kann man sich zunächst einen groben Überblick verschaffen, wieviele Sicherheitslücken in den Bibliotheken im Image enthalten sind:

    docker scout quickview juergenzimmermann/buch:2024.04.0-distroless
    docker scout quickview juergenzimmermann/buch:2024.04.0-bookworm
    docker scout quickview juergenzimmermann/buch:2024.04.0-wolfi

Dabei bedeutet:

C ritical
H igh
M edium
L ow

Sicherheitslücken sind als CVE-Records (CVE = Common Vulnerabilities and Exposures) katalogisiert: https://www.cve.org (ursprünglich: https://cve.mitre.org/cve). Übrigens bedeutet CPE in diesem Zusammenhang Common Platform Enumeration. Die Details zu den CVE-Records im Image kann man durch das Unterkommando cves von Scout auflisten:

    docker scout cves juergenzimmermann/buch:2024.04.0-bookworm
    docker scout cves --format only-packages juergenzimmermann/buch:2024.04.0-bookworm

Statt der Kommandozeile kann man auch den Menüpunkt "Docker Scout" im Docker Dashboard verwenden.

Trivy von Aquasec

Von Aquasec gibt es Trivy, um Docker-Images auf Sicherheitslücken zu analysieren. Trivy gibt es auch als Docker-Image. In compose.trivy.yml ist ein Service für Trivy so konfiguriert, dass das Image buch analysiert wird.

    cd .extras\compose\trivy
    # Analyse des Images mit distroless
    docker compose up

    # Analyse des Images mit Debian Bookworm
    docker compose -f compose.yml -f compose.bookworm.yml up

    # Analyse des Images mit Wolfi
    docker compose -f compose.yml -f compose.wolfi.yml up

OWASP Dependency Check

Mit OWASP Dependency Check werden alle in node_modules installierten npm-Packages mit den CVE-Nummern der NIST-Datenbank abgeglichen, d.h. auch die Packages, die nur als devDependencies installiert wurden. Da es insgesamt zwischen 25.000 und 30.000 Packages sind, dauert dieser Abgleich 30 bis 45 Minuten.

Von https://nvd.nist.gov/developers/request-an-api-key fordert man einen "API Key" an, um im Laufe des Semesters mit OWASP Dependency Check die benutzte Software ("3rd Party Libraries") auf Sicherheitslücken zu prüfen. Diesen API Key trägt man im Skript .extras\dependency-check\dependency-check.ps1 als Wert der Variablen $nvdApiKey ein.

    cd .extras\compose\dependency-check
    docker compose up

Snyk

Zunächst muss man sich bei https://app.snyk.io/account registrieren und dort auch einen Token besorgen. Danach kann man sich folgendermaßen authentifizieren und das Projekt auf Sicherheitslücken überprüfen

    synk auth <MEIN_TOKEN>
    snyk test

AsciiDoctor und PlantUML

Mit AsciiDoctor und PlantUML ist die Dokumentation geschrieben.

Preview von PlantUML-Dateien

Durch das Tastaturkürzel <Alt>d. Dazu ist eine Internet-Verbindung notwendig. Beispiele für PlantUML und AsciiDoctor sind im Unterverzeichnis .extras\doc.

Einstellungen für Preview von AsciiDoctor-Dateien

Zunächst müssen einmalig die Einstellungen (Settings) von VS Code geändert werden. Dazu klickt man in der linken unteren Ecke das Icon ("Rädchen") für die Einstellungen an und wählt den Menüpunkt Einstellungen bzw. Settings aus. Dann gibt man im Suchfeld asciidoc.use_kroki ein und setzt den Haken bei Enable kroki integration to generate diagrams.

Wenn man zum ersten Mal eine .adoc-Datei im Editor öffnet, muss man noch die Verbindung zum PlantUML-Server zulassen, damit die eingebundenen .puml-Dateien in .svg-Dateien konvertiert werden. Dazu gibt man zunächst das <F1> ein und schickt im Eingabefeld das Kommando AsciiDoc: Change Preview Security Settings durch <Enter> ab. Danach wählt man den Unterpunkt Allow insecure content aus.

Preview von AsciiDoctor-Dateien

Durch das Tastaturkürzel <Strg><Shift>v. Dazu ist eine Internet-Verbindung notwendig.

Dokumentation im Format HTML

Die Dokumentation im Format HTML wird in einer Powershell folgendermaßen im Verzeichnis .extras\doc\html erstellt:

    npm run asciidoc

Continuous Integration mit Jenkins

Jenkins wird direkt mit Docker Compose genutzt. Dadurch muss Jenkins nicht immer laufen und kann bei Bedarf gestartet und wieder heruntergefahren werden. Dazu muss zunächst das Jenkins-Image um eine Docker-Installation ergänzt werden, wozu es die Datei Dockerfile.jenkins gibt, um ein solches Image zu erstellen:

    cd .extras\compose\jenkins
    Get-Content Dockerfile | docker run --rm --interactive hadolint/hadolint:2.10.0-beta-debian
    docker build --tag juergenzimmermann/jenkins:2024.04.0 .

Das neu gebaute Image juergenzimmermann/jenkins:2024.04.0 wird in compose.yml beim Service jenkins verwendet:

    cd .extras\compose\jenkins
    docker compose up

    # In einer 2. PowerShell: Herunterfahren
    docker compose down

Aufruf mit Webbrowser

Mit der URL https://localhost:7070 kann man von einem Webbrowser auf den Jenkins-Container zugreifen. Der Benutzername ist admin und das Passwort Inf und WI..

Bash zur evtl. Fehlersuche im laufenden Jenkins-Container

    docker compose exec jenkins bash

Visual Studio Code

Visual Studio Code kann man kostenfrei herunterladen.

Tipps:

<Strg># : Kommentare setzen und entfernen
<F1>: Die Kommandopalette erscheint
<Strg><Shift>v: Vorschau für MarkDown und AsciiDoctor
<Alt>d: Vorschau für PlantUml
https://vscodecandothat.com: Kurze Videos zu VS Code
https://www.youtube.com/watch?v=beNIDKgdzwQ: Video für Debugging

Empfohlene Code-Konventionen

In Anlehnung an die Guidelines von TypeScript

"Feature Filenames", z.B. buch.service.ts
Klassennamen mit PascalCase
Union-Types (mit Strings) statt Enums
Attribute und Funktionen mit camelCase
# für private Properties
private Properties nicht mit vorangestelltem _
Interfaces nicht mit vorangestelltem I
Higher-Order Functions: [...].forEach(), [...].filter() und [...].map()
Arrow-Functions statt function()
undefined verwenden und nicht null
Geschweifte Klammern bei if-Anweisungen
Maximale Dateigröße: 400 Zeilen
Maximale Funktionsgröße: 75 Zeilen

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.extras		.extras
.vscode		.vscode
__tests__		__tests__
scripts		scripts
src		src
.depcheckrc.yml		.depcheckrc.yml
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.STUDENT		.env.STUDENT
.eslintignore		.eslintignore
.eslintrc.cjs		.eslintrc.cjs
.gitattributes		.gitattributes
.gitignore		.gitignore
.hadolint.yaml		.hadolint.yaml
.markdownlint.yml		.markdownlint.yml
.markdownlintignore		.markdownlintignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc.yml		.prettierrc.yml
AUTHORS		AUTHORS
Dockerfile		Dockerfile
Dockerfile.distroless		Dockerfile.distroless
Dockerfile.wolfi		Dockerfile.wolfi
Jenkinsfile		Jenkinsfile
ReadMe.keycloak.md		ReadMe.keycloak.md
ReadMe.md		ReadMe.md
ToDo.md		ToDo.md
Zusammenfassung.md		Zusammenfassung.md
jest.config.js		jest.config.js
nest-cli.json		nest-cli.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
typedoc.cjs		typedoc.cjs

juergenzimmermann/buch

Folders and files

Latest commit

History

Repository files navigation