177 lines
11 KiB
Markdown
177 lines
11 KiB
Markdown
# Java Web Starter (JWS) - University Project Environment Initializer
|
|
|
|
[](https://opensource.org/licenses/MIT) **Dieses Projekt entstand im Rahmen einer wissenschaftlichen Hausarbeit im Modul "Programmieren von Webanwendungen" an der IU Internationale Hochschule.**
|
|
|
|
## Inhaltsverzeichnis
|
|
|
|
- [Motivation / Problemstellung](#motivation--problemstellung)
|
|
- [Lösungsansatz](#lösungsansatz)
|
|
- [Kernfunktionen](#kernfunktionen)
|
|
- [Technologie-Stack](#technologie-stack)
|
|
- [Zielgruppe](#zielgruppe)
|
|
- [Installation](#installation)
|
|
- [Voraussetzungen](#voraussetzungen)
|
|
- [Über Releases (Empfohlen)](#über-releases-empfohlen)
|
|
- [Aus dem Quellcode bauen](#aus-dem-quellcode-bauen)
|
|
- [Benutzung](#benutzung)
|
|
- [Enthaltene Projekt-Templates](#enthaltene-projekt-templates)
|
|
- [Funktionsweise (Dev Container)](#funktionsweise-dev-container)
|
|
- [Bekannte Probleme / Limitationen](#bekannte-probleme--limitationen)
|
|
- [Zukünftige Arbeit / Ausblick](#zukünftige-arbeit--ausblick)
|
|
- [Beitragen](#beitragen)
|
|
- [Lizenz](#lizenz)
|
|
- [Danksagung](#danksagung)
|
|
|
|
## Motivation / Problemstellung
|
|
|
|
Die Einrichtung adäquater Entwicklungsumgebungen stellt besonders in der Lehre eine signifikante Hürde dar. Studierende nutzen oft heterogene Systeme (Betriebssysteme, installierte Software, Konfigurationen), was häufig zu Kompatibilitätsproblemen, zeitaufwendiger Fehlersuche und dem bekannten „Works on my machine“-Problem führt. Dies verursacht Frustration, erhöht den Betreuungsaufwand und lenkt vom eigentlichen Lerninhalt ab. Besonders bei komplexen Technologie-Stacks, wie sie in der Webentwicklung mit Java (z.B. Jakarta EE, Spring Boot, Datenbanken) üblich sind, ist die manuelle Konfiguration fehleranfällig.
|
|
|
|
## Lösungsansatz
|
|
|
|
Dieses Projekt bietet eine plattformübergreifende Desktop-Anwendung (`jws`), die den Prozess der Bereitstellung standardisierter Entwicklungsumgebungen für universitäre Java-Webprojekte radikal vereinfacht. Unter Nutzung von **Docker** für die Containerisierung und dem **Dev Container Standard** ermöglicht das Tool Studierenden, mit wenigen Klicks eine vorkonfigurierte, lauffähige und konsistente Umgebung für spezifische Projektvorlagen zu initialisieren.
|
|
|
|
Das Tool wurde in **Go** mit dem **Fyne** GUI-Toolkit entwickelt, um native Ausführbarkeit unter Windows, macOS und Linux zu gewährleisten
|
|
|
|
## Kernfunktionen
|
|
|
|
- **Plattformübergreifend:** Läuft nativ unter Windows, macOS und Linux.
|
|
- **Abhängigkeitsprüfung:** Überprüft automatisch, ob Docker Desktop und Visual Studio Code installiert sind.
|
|
- **Automatisierte Installation:** Bietet an, fehlende Abhängigkeiten (Docker Desktop, VS Code) systemabhängig zu installieren:
|
|
- **Windows:** Nutzt Winget (prüft auch auf WSL).
|
|
- **macOS:** Nutzt Homebrew (installiert Homebrew bei Bedarf).
|
|
- **Linux:** Nutzt distributionsspezifische Methoden (dpkg/dnf für VS Code, Docker-Installationsskripte).
|
|
- **Template-Auswahl:** Bietet eine Auswahl vordefinierter Starter-Projektvorlagen.
|
|
- **Lokales Deployment:** Kopiert die ausgewählten Template-Dateien in ein vom Benutzer gewähltes Verzeichnis.
|
|
- **VS Code Integration:** Öffnet das erstellte Projektverzeichnis automatisch in Visual Studio Code.
|
|
- **Vorkonfigurierte Umgebungen:** Jedes Template enthält:
|
|
- `Dockerfile(s)`: Definiert das Basis-Image mit JDK, Build-Tools etc..
|
|
- `docker-compose.yml`: Definiert die Dienste (App-Container, PostgreSQL-Datenbank, ggf. Runtime-Container wie Open Liberty) und Netzwerke.
|
|
- `devcontainer.json`: Konfiguriert VS Code für die Nutzung des Containers, installiert notwendige Extensions (z.B. Java Extension Pack) und richtet Port-Weiterleitungen ein.
|
|
- Projekt-Grundgerüst mit vorkonfigurierter Hibernate-Datenbankanbindung.
|
|
|
|
## Technologie-Stack
|
|
|
|
- **Kernanwendung:** Go, Fyne Toolkit
|
|
- **Containerisierung:** Docker, Docker Compose
|
|
- **Standardisierung:** Dev Container Standard (`devcontainer.json`)
|
|
- **Ziel-IDE:** Visual Studio Code
|
|
- **Abhängigkeitsinstallation (Helfer):** Winget (Windows), Homebrew (macOS), Shell-Befehle (Linux)
|
|
- **Projekt-Templates:**
|
|
- Java Frameworks: Jakarta EE (Servlet/JSP, JSF, REST), Spring Boot (REST)
|
|
- Persistenz: Hibernate (JPA)
|
|
- Datenbank: PostgreSQL
|
|
- Build-Tools: Maven / Gradle (implizit)
|
|
|
|
## Zielgruppe
|
|
|
|
- **Studierende:** Insbesondere in Informatik- und Wirtschaftsinformatik-Studiengängen, die Java-Webanwendungen programmieren und eine einfache, fehlerfreie Setup-Erfahrung wünschen.
|
|
- **Lehrende:** Die ihren Studierenden standardisierte Umgebungen zur Verfügung stellen möchten, um den Support-Aufwand zu reduzieren und die Konzentration auf Lerninhalte zu fördern.
|
|
|
|
## Installation
|
|
|
|
### Voraussetzungen
|
|
|
|
- Ein unterstütztes Betriebssystem: Windows 10/11, macOS, gängige Linux-Distributionen (getestet unter Mint, Ubuntu, Fedora).
|
|
- Administratorrechte (werden ggf. für die Installation von Docker/VS Code benötigt).
|
|
- Unter Windows: Eine funktionierende Winget-Installation wird empfohlen/benötigt für die automatische Installation. WSL wird ggf. benötigt und aktiviert.
|
|
- Unter macOS: Homebrew wird empfohlen/benötigt (kann vom Tool installiert werden).
|
|
- Für das Bauen aus dem Quellcode: Eine aktuelle Go-Installation.
|
|
|
|
### Über Releases (Empfohlen)
|
|
|
|
Die einfachste Methode ist das Herunterladen einer vorkompilierten Version für Ihr Betriebssystem von der [**Releases-Seite**](https://codeberg.org/Pata1704/jws_gui/releases) . Laden Sie die passende Datei herunter, entpacken Sie sie ggf. und führen Sie die `jws` aus.
|
|
|
|
### Aus dem Quellcode bauen
|
|
|
|
1. Klonen Sie das Repository:
|
|
```bash
|
|
git clone https://codeberg.org/Pata1704/jws_gui.git
|
|
cd jws_gui
|
|
```
|
|
2. Installieren Sie die von [Fyne](https://docs.fyne.io/started/) definierten Abhängigkeiten für ihr Betriebssytem
|
|
3. Bauen Sie die Anwendung:
|
|
```bash
|
|
go build .
|
|
```
|
|
Dies erstellt die ausführbare Datei `jws` (oder `jws.exe` unter Windows) im aktuellen Verzeichnis.
|
|
|
|
## Benutzung
|
|
|
|
1. **Starten Sie die Anwendung** (`jws`). Ein Info-Fenster weist auf wichtige Punkte hin.
|
|
2. **Abhängigkeits-Check:** Die Anwendung prüft, ob Docker Desktop und Visual Studio Code installiert sind ("Dependency Screen").
|
|
- Falls etwas fehlt, klicken Sie auf die entsprechenden Buttons, um die Installation anzustoßen. Folgen Sie den Anweisungen (ggf. sind Admin-Rechte nötig). Ein Fortschrittsbalken wird angezeigt.
|
|
3. **Template-Auswahl:** Sobald alle Abhängigkeiten erfüllt sind, gelangen Sie zum "Project Screen". Wählen Sie hier das gewünschte Projekt-Template aus (z.B. "JakartaEE Todo-App mit JSP").
|
|
4. **Deployment:** Klicken Sie auf "Deploy". Wählen Sie im Dialog einen Zielordner auf Ihrem Rechner aus und bestätigen Sie. Die Template-Dateien werden dorthin kopiert.
|
|
5. **Öffnen in VS Code:** Die Anwendung öffnet das erstellte Projektverzeichnis automatisch in Visual Studio Code.
|
|
6. **In Container öffnen:**
|
|
- Stellen Sie sicher, dass Docker Desktop läuft.
|
|
- VS Code sollte eine Benachrichtigung anzeigen: "Folder contains a Dev Container configuration file. Reopen folder to develop in a container?". Klicken Sie auf "**Reopen in Container**".
|
|
- (Falls die Benachrichtigung nicht erscheint: Klicken Sie auf das blaue Icon `><` unten links in der VS Code Statusleiste oder nutzen Sie die Befehlspalette (Ctrl+Shift+P) und suchen Sie nach "Dev Containers: Reopen in Container".
|
|
7. **Build & Run:** Docker/VS Code bauen nun das Image und starten die Container (dies kann beim ersten Mal etwas dauern). Sobald die Umgebung bereit ist, können Sie im integrierten Terminal von VS Code arbeiten, als wären Sie direkt im Container.
|
|
- **Beispiel (für JakartaEE JSP Template):** Führen Sie im VS Code Terminal aus:
|
|
```bash
|
|
mvn clean package && sudo cp target/*.war /app/
|
|
```
|
|
Dieser Befehl kompiliert das Projekt und kopiert die `.war`-Datei in das Deployment-Verzeichnis des laufenden OpenLiberty-Servers.
|
|
8. **Zugriff:** Nach kurzer Zeit ist die Beispielanwendung im Browser unter `http://localhost:9080/todo-app` (oder einem ähnlichen Port/Pfad je nach Template) erreichbar.
|
|
|
|
Sie haben nun eine funktionierende, containerisierte Entwicklungsumgebung, ohne sich manuell um Installationen oder Konfigurationen kümmern zu müssen!
|
|
|
|
## Enthaltene Projekt-Templates
|
|
|
|
Aktuell sind folgende Templates enthalten:
|
|
|
|
1. Jakarta EE mit Servlet/JSP
|
|
2. Jakarta EE mit JSF
|
|
3. Jakarta EE mit REST (JAX-RS)
|
|
4. Spring Boot mit REST
|
|
|
|
Alle Templates beinhalten eine PostgreSQL-Datenbankanbindung via Hibernate/JPA.
|
|
|
|
## Funktionsweise (Dev Container)
|
|
|
|
Der Kern der Standardisierung basiert auf dem **Dev Container Standard**:
|
|
|
|
1. Die `devcontainer.json`-Datei im Projektwurzelverzeichnis teilt VS Code mit, wie die Entwicklungsumgebung konfiguriert ist.
|
|
2. Sie verweist meist auf eine `docker-compose.yml`-Datei, die die notwendigen Dienste (Applikationscontainer, Datenbank etc.) definiert.
|
|
3. Die `Dockerfile(s)` definieren, wie die einzelnen Container-Images gebaut werden (Basis-Image, JDK, Tools, Abhängigkeiten).
|
|
4. Wenn Sie das Projekt in VS Code "im Container öffnen", startet VS Code die definierten Docker-Container und verbindet sich mit dem spezifizierten Entwicklungscontainer.
|
|
5. VS Code installiert automatisch die in der `devcontainer.json` festgelegten Extensions _innerhalb_ des Containers.
|
|
6. Sie arbeiten in VS Code (Terminal, Debugger, Code-Editor) nahtlos innerhalb dieser isolierten, vorkonfigurierten Umgebung.
|
|
|
|
Dies stellt sicher, dass alle Nutzer exakt die gleiche Umgebung mit den richtigen Werkzeugversionen und Abhängigkeiten haben, unabhängig von ihrem lokalen System.
|
|
|
|
## Bekannte Probleme / Limitationen
|
|
|
|
- **SELinux (Fedora):** Unter Fedora mit aktiviertem SELinux kann es zu Problemen beim Mounten von Host-Verzeichnissen in Docker-Containern kommen. Ein Workaround ist `sudo setenforce 0` (nicht empfohlen), eine korrekte SELinux-Konfiguration für Docker ist komplexer.
|
|
- **Abhängigkeit von Paketmanagern:** Die automatische Installation hängt vom Funktionieren externer Tools wie Winget und Homebrew ab. Fehler in diesen Tools können die Installation behindern.
|
|
- **Manuelle Schritte:** Docker Desktop muss manuell gestartet werden, bevor "Reopen in Container" funktioniert
|
|
- **Installation Robustheit:** Obwohl auf mehreren Systemen getestet, kann es auf spezifischen Konfigurationen zu Problemen kommen
|
|
- **Evaluation:** Bisher hauptsächlich technisch und durch Experten-Feedback evaluiert. Eine breite Evaluation mit Studierenden (Usability, Zeitersparnis) steht noch aus
|
|
|
|
## Zukünftige Arbeit / Ausblick
|
|
|
|
- Verbesserung der Robustheit der Installationsprozesse
|
|
- UI-Verbesserungen und automatische Sprachanpassung
|
|
- Erweiterung um zusätzliche Templates (z.B. andere Java-Versionen, Microservices, spezifische Bibliotheken)
|
|
- Plugin-System für Lehrende zur einfachen Erstellung eigener Templates
|
|
- Unterstützung für Git-Repositories als Template-Quelle
|
|
- Einführung einer Wahl der IDE (IntelliJ IDEA, Eclipse, NeoVim, Zed, Fleet)
|
|
- Umfassende quantitative Evaluation
|
|
|
|
## Beitragen
|
|
|
|
Beiträge sind willkommen!
|
|
|
|
## Software Bill of Materials (SBOM)
|
|
Das SBOM dieses Projekts finden Sie unter [sbom.json](sbom.json).
|
|
|
|
## Lizenz
|
|
|
|
Dieses Projekt ist lizenziert unter der MIT Lizenz
|
|
|
|
## Danksagung
|
|
|
|
- Danke an meinem Dozenten im Modul "Programmieren von Webanwendungen" für die Betreuung der ursprünglichen Hausarbeit.
|
|
- Danke an die Teilnehmer der Umfrage für ihr wertvolles Feedback.
|
|
- Inspiration durch die Konzepte von Docker, Dev Containers und die Arbeiten von Malan et al. und Valstar et al. .
|