docs: update README
This commit is contained in:
parent
3abd4a985a
commit
8e48aa6a09
1 changed files with 136 additions and 65 deletions
201
README.md
201
README.md
|
|
@ -1,103 +1,174 @@
|
|||
# JakartaEE & Spring Boot Starter
|
||||
# Java Web Starter (JWS) - University Project Environment Initializer
|
||||
|
||||
This application is a GUI tool developed in Go using the Fyne framework (v2.5.4). It helps users set up a development environment for JakartaEE and Spring Boot projects by checking and installing necessary dependencies, and then allowing users to deploy starter projects.
|
||||
[](https://opensource.org/licenses/MIT) **Dieses Projekt entstand im Rahmen einer wissenschaftlichen Hausarbeit im Modul "Programmieren von Webanwendungen" an der IU Internationale Hochschule.**
|
||||
|
||||
## Features
|
||||
## Inhaltsverzeichnis
|
||||
|
||||
- _Dependency Check_: Verifies the installation of required tools (Visual Studio Code and Docker).
|
||||
- [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)
|
||||
|
||||
- _Automatic Installation_: Offers to install missing dependencies on supported platforms.
|
||||
## Motivation / Problemstellung
|
||||
|
||||
- _Project Selection_: Provides a list of starter projects for JakartaEE and Spring Boot.
|
||||
Die Einrichtung adäquater Entwicklungsumgebungen stellt besonders in der Lehre eine signifikante Hürde dar. Studierende nutzen oft heterogene Systeme (Betriebssysteme, installierte Software, Konfigurationen) [source: 9], 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.
|
||||
|
||||
- _Project Deployment_: Allows users to deploy selected projects and open them in Visual Studio Code with dev containers.
|
||||
## Lösungsansatz
|
||||
|
||||
## Prerequisites
|
||||
Dieses Projekt bietet eine plattformübergreifende Desktop-Anwendung (`jws-Executable`), 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.
|
||||
|
||||
- Go 1.23 or later
|
||||
Das Tool wurde in **Go** mit dem **Fyne** GUI-Toolkit entwickelt, um native Ausführbarkeit unter Windows, macOS und Linux zu gewährleisten
|
||||
|
||||
- Fyne v2.5.4
|
||||
## 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
|
||||
|
||||
### Option 1: Download Pre-built Binary
|
||||
### Voraussetzungen
|
||||
|
||||
Go to the Releases page of this repository.
|
||||
- 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 [source: 166, 246]. 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.
|
||||
|
||||
Download the appropriate binary for your operating system.
|
||||
### Über Releases (Empfohlen)
|
||||
|
||||
### Option 2: Build from Source
|
||||
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.
|
||||
|
||||
- Clone the repository:
|
||||
### Aus dem Quellcode bauen
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/jws_gui.git
|
||||
```
|
||||
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.
|
||||
|
||||
Navigate to the project directory:
|
||||
## Benutzung
|
||||
|
||||
```bash
|
||||
cd jws_gui
|
||||
```
|
||||
1. **Starten Sie die Anwendung** (`jws-Executable`). 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?" [source: 221]. 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.
|
||||
|
||||
Install dependencies:
|
||||
Sie haben nun eine funktionierende, containerisierte Entwicklungsumgebung, ohne sich manuell um Installationen oder Konfigurationen kümmern zu müssen!
|
||||
|
||||
The list of dependencies required for the development of Fyne Apps can be found at “https://docs.fyne.io/started/”.
|
||||
## Enthaltene Projekt-Templates
|
||||
|
||||
```bash
|
||||
go mod tidy
|
||||
```
|
||||
Aktuell sind folgende Templates enthalten:
|
||||
|
||||
Build the application:
|
||||
1. Jakarta EE mit Servlet/JSP
|
||||
2. Jakarta EE mit JSF
|
||||
3. Jakarta EE mit REST (JAX-RS)
|
||||
4. Spring Boot mit REST
|
||||
|
||||
```bash
|
||||
go build
|
||||
```
|
||||
Alle Templates beinhalten eine PostgreSQL-Datenbankanbindung via Hibernate/JPA.
|
||||
|
||||
## Usage
|
||||
## Funktionsweise (Dev Container)
|
||||
|
||||
Run the application:
|
||||
Der Kern der Standardisierung basiert auf dem **Dev Container Standard**:
|
||||
|
||||
If you downloaded a pre-built binary:
|
||||
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.
|
||||
|
||||
```bash
|
||||
./jakartaee-springboot-starter
|
||||
```
|
||||
Dies stellt sicher, dass alle Nutzer exakt die gleiche Umgebung mit den richtigen Werkzeugversionen und Abhängigkeiten haben, unabhängig von ihrem lokalen System.
|
||||
|
||||
or by double-clicking the excutable.
|
||||
## Bekannte Probleme / Limitationen
|
||||
|
||||
If you built from source:
|
||||
- **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 [source: 235], 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
|
||||
|
||||
```bash
|
||||
./jakartaee-springboot-starter
|
||||
```
|
||||
## Zukünftige Arbeit / Ausblick
|
||||
|
||||
The application will launch a GUI window where you can:
|
||||
- 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
|
||||
|
||||
1. Check and install dependencies (Visual Studio Code and Docker).
|
||||
2. Select a starter project from the available options.
|
||||
3. Deploy the selected project and open it in Visual Studio Code.
|
||||
## Beitragen
|
||||
|
||||
## Project Structure
|
||||
Beiträge sind willkommen!
|
||||
|
||||
_TODO_
|
||||
## Lizenz
|
||||
|
||||
## Customization
|
||||
Dieses Projekt ist lizenziert unter der MIT Lizenz
|
||||
|
||||
To add new starter projects:
|
||||
## Danksagung
|
||||
|
||||
1. Create a new project template in the projects/ directory.
|
||||
2. Add the project details to the projects.json file.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
License
|
||||
[Insert your chosen license here]
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- Fyne: https://fyne.io/
|
||||
- JakartaEE: https://jakarta.ee/
|
||||
- Spring Boot: https://spring.io/projects/spring-boot
|
||||
- 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. .
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue