WebBox

Das Internet ist als Verbindung von Netzknoten konzipiert, die Inhalte bereit stellen. Die WebBox etabliert einen solchen Netzknoten als persönliche Instanz eines Nutzers und ermöglicht es, eigene Inhalte über das Netz zu verwalten und zu teilen. Dieses Dokument beschreibt die WebBox im Detail.

1. Über die WebBox

Mit der WebBox können Inhalte so verwaltet werden, wie es Nutzer vom Desktop handelsüblicher Betriebssyteme her kennen. Zur Bedienung wird nicht mehr als ein Browser benötigt. Von überallher können Texte und Dokumente bearbeitet, Bilder, Musik oder Videos organisiert, kopiert, verschoben oder herauf- und heruntergeladen werden.

Die Kopie in einen öffentlichen Ordner genügt und Inhalte erscheinen für jedermann sichtbar im Netz. Der Rest bleibt im privaten Bereich nur für den Nutzer zugänglich, dem sie gehören. Rollen und Berechtigungen können über die Nutzerverwaltung verwaltet werden.

Die WebBox etabliert zudem ein relationales Datenbankmanagementsystem und lässt sich mit Java-Webanwendungen beliebig erweitern.

1.1. Zielgruppe

Die Beschreibung in diesem Dokument beschränkt sich auf eine Nutzung mit Linux. Eine WebBox läuft darüber hinaus auch auf anderen Betriebssystemen wie Mac OS oder Windows.

Die WebBox ist mit dem Einsatz für einzelne Personen, Familien, oder kleine Arbeitsgruppen im Sinn entstanden. Sie funktioniert unverändert auch für eine größere Anzahl an Benutzern, allerdings ist ein großer Nutzerkreis eher etwas für das Zusammenspiel vieler WebBoxen.

Ein Betrieb vieler WebBoxen aus einer Hand erfordert zusätzliche Konfiguration für Cluster, weitere Infrastruktur und deren Orchestrierung. Der Betrieb in einem solchen Szenario ist möglich, aber in diesem Dokument nicht abgedeckt.

1.2. Lizenz

Die WebBox wird unter den Bedingungen der GNU Affero General Public License bereitgestellt.

2. Installation

Zur Installation einer WebBox werden eine Kommandozeile geöffnet und die folgenden Kommandos ausgeführt:

Kommandos zur Installation einer WebBox in ein beispielhaftes Benutzerverzeichnis /home/fred
# ins Benutzerverzechnis wechseln
cd /home/fred

# das Installationsskript laden
wget https://uhilger.de/data/pg/webbox/dl/make-wbx

# das Skript ausführbar machen
chmod ug+x make-wbx

# die Teile der WebBox laden und zusammenstellen
./make-wbx

Es werden keine Eingriffe im System der Zielmaschine vorgenommen, alles beschränkt sich auf das Benutzerverzeichnis: Die obigen Kommandos legen im Ordner /home/fred einen neuen Ordner wbx-inst an, laden alle Bestandteile einer WebBox herunter und machen sie ausführbar. Über eine Internet-Verbindung mit 100 Mbit oder mehr dauert dieser Vorgang weniger als eine Minute.

Die ausführbare Fassung der WebBox liegt anschließend im Ordner /home/fred/wbx-inst/wbx.

Dieser Ordner wird im weiteren Verlauf dieses Dokuments $WBX-INST genannt, d.h., wenn im Dokument $WBX-INST erscheint, ist /home/fred/wbx-inst/wbx gemeint. Die WebBox kann nun von dort gestartet werden wie in Kapitel Starten und Stoppen beschrieben. Abweichend vom Betrieb laut Installation kann die WebBox auch mit einer eigenen Konfiguration ausgeführt werden.

2.1. WebBox sichern

Die hier beschriebene Installation ist nur für Testzwecke geeignet. Um eine WebBox sicher produktiv zu benutzen, sollte sie zusammen mit einem Proxy wie Lighttpd betrieben werden. Grob gesagt ist hierfür das Vorgehen wie folgt:

  1. Lighttpd installieren (auf Ubuntu z.B. mit sudo apt-get install lighttpd)

  2. Ein TLS-Zertifikat erzeugen, z.B. bei Let’s Encrypt

  3. Die verschlüsselte Kommunikation unter Verwendung des Zertifikats in der Konfiguration von Lighttpd einrichten

  4. In der Konfiguration von Lighttpd eine Weiterleitung auf die WebBox eintragen

Die Kommunikation erfolgt auf diese Weise verschlüsselt und ist abgesichert gegen das Mitlesen unbefugter Dritter.

2.1.1. Verschlüsselung ohne Proxy

Die WebBox kann auch ohne Proxy verschlüsselt kommunizieren. Für diese Variante ist eine .keystore-Datei im Verzeichnis $WBX-INST/.conf/prg/tc-base/conf erforderlich, in die das TLS-Zertifikat eingetragen wird. In der Datei $WBX-INST/.conf/prg/tc-base/conf/server.xml muss dann ein Konnektor für HTTPS konfiguriert werden.

Das Vorgehen hierfür ist z.B. im Beitrag HTTPS bei Tomcat aktivieren beschrieben.

2.2. Zielsystem einstellen

Das Installationsskript make-wbx ist im Auslieferungszustand für ein 64-Bit x86-Linux konfiguriert. Zur Verwendung auf Maschinen mit anderem Prozessor oder Betriebssystem muss der Uniform Resource Locator (URL) der passenden Java-Version ermittelt werden. Das kann z.B. bei Azul oder AdoptOpenJDK geschehen.

Der URL muss vor der Ausführung im Parameter JAVA_URL des Skripts make-wbx eingetragen werden.

3. Starten und Stoppen

Die WebBox ist standardmäßig darauf eingerichtet, mit den installierten Bestandteilen zu starten. Soll die Ablaufumgebung anders konfiguriert sein, muss vor dem ersten Start das Start- / Stoppskript der WebBox von Hand angepasst werden wie in Eigene Konfiguration beschrieben.

3.1. Starten

Zum Starten der WebBox wird eine Kommandozeile geöffnet, in den Ordner der WebBox navigiert und das Kommando zum Start gegeben:

cd /home/fred/wbx-inst/wbx
./wbx start

Auf der Kommandozeile erscheint die Meldung WebBox Startsequenz durchgeführt, die WebBox kann im Browser aufgerufen werden. Vor der ersten Verwendung müssen noch Benutzer angelegt werden.

3.2. Stoppen

Das Stoppen der WebBox erfolgt mit folgenden Befehlen auf der Kommandozeile:

cd /home/fred/wbx-inst/wbx
./wbx stop

Die WebBox wird heruntergefahren, auf der Kommandozeile erscheint die Meldung WebBox Stoppsequenz durchgeführt.

3.3. Benutzer anlegen

Beim ersten Start der WebBox wird automatisch der Benutzer admin mit Kennwort admin erstellt. Dieser Nutzer sollte gleich als Erstes verwendet werden, um einen anderen Benutzer mit Administrationsrechten anzulegen. Der neue Administrator-Benutzer muss mindestens die Rolle nutzerAdmin erhalten.

Die dazu erforderliche Nutzerverwaltung wird auf der Startseite der WebBox über das Menü oben rechts aufgerufen. Die Bedienung der Nutzerverwaltung ist in der Anleitung beschrieben.

Sobald nach der Konfiguration die Anmeldung mit dem neu angelegten Adminstrator-Benutzer gelingt, kann später der Benutzer admin gelöscht werden.

Zur Bedienung der Dateiverwaltung benötigen Benutzer zudem die Rolle ownFileAdmin. Zum Ändern des eigenen Kennwortes kann Benutzern die Rolle nutzerProfil zugewiesen werden.

4. Bedienung

Nach erfolgreicher Installation und ggf. eigener Konfiguration kann die WebBox genutzt werden. In diesem Abschnitt ist ihre Bedienung beschrieben. Das Kapitel WebBox erweitern beschreibt zudem Möglichkeiten, den Bedienungsumfang zu erweitern.

4.1. WebBox aufrufen

Wird nach dem Start der WebBox im Webbrowser der URL http://localhost:8089/ aufgerufen, erscheint die Startseite der WebBox.

wbx-browser
Abb. 1. die Startseite der WebBox

Für die WebBox ist der Port 8089 voreingestellt, er kann geändert werden wie in Abschnitt Port beschrieben. Die Standard-Begrüßungsseite kann durch eigene Inhalte ersetzt werden, indem diese Inhalte im Verzeichnis der WebBox Root App abgelegt werden.

4.2. Sichtbarkeit von Inhalten

Die WebBox unterscheidet für jeden Benutzer einen öffentlichen und einen nicht öffentlichen, persönlichen Bereich. Im öffentlichen Bereich befindliche Inhalte sind ohne Einschränkung sichtbar. Inhalte im persönlichen Bereich sind nur für den angemeldeten Benutzer sichtbar. Jeder angemeldete Benutzer sieht dabei im persönlichen Bereich nur seine eigenen Inhalte. Beide Bereiche sind mit einem eigenen Uniform Resource Locator (URL) zugänglich:

http://localhost:8089/home/[benutzername]/ (persönliche Inhalte)

http://localhost:8089/data/[benutzername]/ (öffentliche Inhalte)

Die URLs für persönliche und öffentliche Inhalte wie sie oben beschrieben sind geben dabei Inhalte aus den Ordnern Persoenlich und Oeffentlich der WebBox wieder. Deren Inhalt wird erstellt und verwaltet wie in den folgenden Kapiteln beschrieben.

4.2.1. Inhalte ansehen

Über den Punkt Ansehen im Menü Datei wird der Inhalt einer gerade gewählten Datei im Browser angezeigt. Auf diese Weise lässt sich auch der Uniform Resource Locator (URL) bestimmen, mit dem die Datei im Browser direkt aufgerufen werden kann. Es werden so nur Inhalte dargestellt, die im Browser angesehen werden können, z.B. Texte, HTML-Dateien, PDF, Bilder, Videos, usw.

Dateien mit nicht darstellbaren Formaten wie z.B. ZIP-Dateien oder Office-Dateien (Microsoft, OpenOffice, LibreOffice) werden heruntergeladen.

4.2.2. Inhalte hochladen

Lokale Inhalte werden zur WebBox übertragen und im aktuell geöffneten Ordner abgelegt, wenn sie per Ziehen und Ablegen (Drag and Drop) im gerade geöffneten Ordner der Dateiverwaltung 'fallengelassen' werden.

Einzelne und mehrere gleichzeitig ausgewählte Dateien können so direkt an die WebBox übertragen werden. Sollen ganze Ordner übertragen werden, müssen diese zuvor als ZIP-Datei gepackt werden.

4.3. Dateien bearbeiten

Die WebBox ist mit einer Dateiverwaltung ausgestattet, mit der Dateien erstellt und deren Inhalte bearbeitet werden können. Die Dateiverwaltung der WebBox wird über den Punkt Dateiverwaltung des Menüs oben rechts auf der Startseite der WebBox aufgerufen.

Beim Aufruf erscheint zunächst die Anmeldeseite. Nutzer benötigen die Rolle ownFileAdmin, um die Dateiverwaltung benutzen zu können. Mit erfolgreicher Anmeldung erscheint die Dateiverwaltung.

img-wbx-file-cms
Abb. 2. Die Dateiverwaltung der WebBox

Mit Klick auf den Ordner Persoenlich wird dessen Inhalt angezeigt, anfangs ist dieser leer. Auswahl des Punkts Neuer Text…​ im Menü Datei öffnet den Texteditor.

img-wbx-txt-editor
Abb. 3. der Texteditor der WebBox

Hier kann nun beliebiger Textinhalt eingetragen werden. Auswahl des Punkts Speichern oder Speichern unter.. im Menü Datei fragt einen Namen für die neue Datei ab.

img-wbx-file-save-as
Abb. 4. der Dialog Datei speichern unter

Mit Betätigen der Schaltfläche Speichern wird die neue Textdatei unter dem eingetragenen Namen in dem Ordner gespeichert, von dem aus der Texteditor gestartet wurde, in diesem Fall also im Ordner Persoenlich. Die Auswahl Schließen aus dem Menü Datei schließt den Texteditor und es wird wieder der Inhalt des Ordners Persoenlich angezeigt. Dort ist jetzt die neu angelegte Datei dargestellt.

Zum Bearbeiten einer Textdatei wird diese zunächst angeklickt und so ausgewählt. Dann wählt man Als Text öffnen aus dem Menü Datei.

4.4. Textdokumente bearbeiten

Mit der Dateiverwaltung lassen sich auch Textdokumente schreiben und bearbeiten. Die Vorgehensweise ist genauso wie im vorigen Abschnitt für Textdateien beschrieben. Für Textdokumente wird Neues Dokument aus dem Menü Datei gewählt, woraufhin sich der Dokumenteditor der Dateiverwaltung öffnet.

img-wbx-dok-editor
Abb. 5. Der Dokumenteditor der WebBox

Hier kann ein Textdokument mit Formatierungen direkt im Browser erstellt und bearbeitet werden, wie man es von üblichen Textverarbeitungen gewohnt ist. Das Speichern oder Bearbeiten erfolgt wie im vorigen Abschnitt beschrieben. Textdokumente werden dabei als reines HTML gespeichert, der Autor benötigt keine HTML-Kenntnisse für das Schreiben oder Bearbeiten. Die Dokumente sind so bestens für die Verwendung im Netz geeignet.

4.4.1. Textdokumente und HTML-Seiten

Ein Textdokument, wie es mit der WebBox erstellt werden kann, ist einer HTML-Seite ähnlich. Es beinhaltet aber nur den Teil einer HTML-Seite, der im Element body untergebracht ist. Zu vollwertigen HTML-Seiten fehlt den Textdokumenten der WebBox die Gesamtstruktur mit dem Kopf-Teil, dem HTML-Element head.

Werden Textdokumente der WebBox mit der Funktion Inhalte ansehen dargestellt, also über ihren URL aufgerufen, gibt die WebBox das Textdokument wie eine HTML-Seite aus. Mangels Angaben im Kopf der Seite verwendet der Webbrowser Standardeinstellungen für die Gestaltung des Dokuments. Die Darstellung kann deshalb von Browser zu Browser unterschiedlich ausfallen.

Wird beim Speichern des Textdokuments die Endung .htmi im Namen angegeben, bettet die WebBox den Inhalt des Textdokuments in eine komplette HTML-Struktur bestehend aus head- und body-Element ein und fügt Verweise auf Gestaltungsvorlagen hinzu (CSS-Stylesheets). Als Gestaltungsvorlage wird das der WebBox beiliegende Stylesheet von Bootstrap $WBX-INST/apps/jslib/bootstrap/css/bootstrap.min.css sowie die Datei stile.css eingebettet. Ist im Ordner, in dem das betreffende Textdokument abgelegt ist, eine Datei stile.css abgelegt, können dem Textdokumente auf diese Weise eigene Gestaltungsvorgaben mitgegeben werden.

4.4.2. Textdokumente als HTML exportieren

Um ein Textdokument, das mit der WebBox erstellt wurde, auch ohne eine WebBox einfach im Browser ansehen zu können, muss es als HTML-Seite vorliegen. Mit dem Punkt Export HTML im Menü Datei können alle Textdokumente mit Endung .htmi des aktuell geöffneten Ordners als HTML-Seiten erzeugt werden.

Die so erzeugten HTML-Seiten werden in einen Ordner gelegt, der so heißt wie der aktuell geöffnete Ordner nebst Zusatz _html. Der neue Ordner liegt nach dem HTML-Export in dem Ordner, in dem der aktuell geöffnete Ordner liegt.

4.5. Ordner

Mit den Punkt Neuer Ordner im Menü Datei wird im gerade angezeigten Ordner ein neuer Ordner erstellt. Nach Eingabe eines Ordner-Namens wird der neue Ordner im aktuell geöffneten Ordner angelegt. Ordner und deren Inhalte können mit den Optionen im Menü Bearbeiten verschoben, kopiert oder gelöscht werden. Hierzu werden folgende Schritte ausgeführt

  1. Inhalt (Ordner oder Datei) durch Anklicken auswählen,

  2. Menü Bearbeiten - Kopieren oder Ausschneiden wählen,

  3. in den Ordner navigieren, in den der ausgewählte Inhalt verschoben oder kopiert werden soll und

  4. Menü Bearbeiten - Einfügen wählen.

Die gewählten Inhalte werden kopiert bzw. verschoben und befinden sich anschließend am gewählten Ort. Zur Auswahl mehrerer Dateien oder Ordner muss beim Anklicken jedes Elements einer Mehrfachauswahl die Strg-Taste festgehalten werden.

4.5.1. Neuer Reiter und direkter Aufruf (Lesezeichen)

Mit dem Punkt Neuer Reiter im Menü Datei wird der gerade geöffnete Ordner in einem neuen Aktenreiter (Tab) des Browsers geöffnet. Browser ohne Unterstützung der Darstellung mehrerer Tabs öffnen den Ordner in einem neuen Fenster.

Gegebenenfalls muss in der Konfiguration des Browsers das Öffnen neuer Tabs oder Fenster für die WebBox erlaubt werden. In diesem Fall wird vom Browser beim Aufruf des Punkts Neuer Reiter die Erlaubnis vom Benutzer abgefragt.

Der Uniform Resource Locator (URL) eines so geöffneten Ordners der WebBox erscheint in der Adresszeile des Browsers. Er kann als Lesezeichen zum direkten Aufruf des Ordners gespeichert werden.

4.5.2. Ordner packen

Der Inhalt des gerade geöffneten Ordners kann mit dem Punkt Ordner packen im Menü Datei in ein ZIP-Archiv überführt werden. Das ZIP-Archiv heißt so wie der Ordner und liegt anschließend in dem Ordner, der den gepackten Ordner enthält, also eine Ordnerebene höher.

Wird beispielsweise der Ordner namens Testordner im Pfad Persoenlich/meine-Daten/Texte geöffnet und auf diese Weise gepackt, liegt anschließend eine ZIP-Datei namens Testordner.zip im Ordner Persoenlich/meine-Daten/Texte.

Wird die ZIP-Datei ausgewählt (angeklickt) und der Punkt Ansehen im Menü Datei gewählt, wird die ZIP-Datei heruntergeladen.

4.5.3. Archiv entpacken

Ein ZIP-Archiv wird mit dem Punkt Entpacken im Menü Datei entpackt. Der Inhalt wird direkt in den Ordner entpackt, in dem die ZIP-Datei liegt. Es muss vor dem Entpacken ein neuer Ordner angelegt und die ZIP-Datei dorthin verschoben werden, wenn der Inhalt des ZIP-Archivs nicht mit anderen Inhalten vermischt werden soll.

4.6. WebDAV verwenden

WebDAV ist ein Standardprotokoll für die Verwaltung von Dateien über HTTP oder HTTPS. Es gibt viele Dateiverwaltungs-Apps, die WebDAV unterstützen, beispielsweise auch für iOS oder Android. Mit solchen Programmen ist es sehr einfach, z.B. Fotos vom Mobilgerät auf die WebBox zu übertragen.

Über folgende URLs kann per WebDAV auf die WebBox zugegriffen werden.

http://localhost:8089/dav

dav://localhost:8089/dav

Die URLs verweisen auf den Ordner $WBX-INST/data/dav der WebBox. Inhalte dieses Ordners erscheinen im Ordner Austausch der Dateiverwaltung, der auf der obersten Ebene der Ablagestruktur zusammen mit den Ordnern Persönlich und Öffentlich zu sehen ist.

Wird mit einem WebDAV-fähigen Programm einer der obigen URLs aufgerufen, wird eine Authentifizierung abgefragt. Nur Benutzer der WebBox mit der Rolle davNutzer können sich dort anmelden.

4.7. Bilder

Werden Bilder des Typs JPEG, PNG oder GIF auf die WebBox übertragen, übernimmt die WebBox automatisch das Verkleinern des Originals zu gebräuchlichen anderen Formaten.

Auf diese Weise müssen nicht die unter Umständen großen Datenmengen des Originalbildes für eine Miniatur-Vorschau übertragen werden. Die so erzeugte Miniaturansicht erscheint für Bilder auch anstelle eines Dateisymbols. Neben der Miniaturansicht lassen sich die folgenden weiteren Bildgrößen erzeugen:

Tabelle 1. Bildgrößen und -endungen
Größe (px) Endung

120

_tn

240

_kl

500

_dd

700

_mt

1200

_gr

Dem Namen der Originaldatei eines Bildes wird einfach die Endung der gewünschten Größe angehängt um anstelle des Bildes in Originalgröße die gewünschte Größe aufzurufen. Ohne Endung wird das Bild in Originalgröße ausgegeben.

Ist beispielsweise eine Bilddatei MeinBild.png im Ordner Persoenlich/Bilder des Nutzers fred abgelegt, kann ihre Minituransicht mit folgendem URL angesehen werden:

http://localhost:8098/home/fred/Bilder/MeinBild_tn.png

Bilder können mit Hilfe des Dokumenteditors in Dokumente eingebunden werden. Vom Ablageort des betreffenden Dokuments ausgehend genügt eine relative Pfadangabe. Zum Beispiel könnte ein Dokument im Ordner Persoenlich des Nutzers fred das oben erwähnte Bild mit der relativen Angabe Bilder/MeinBild.png einbinden.

4.7.1. Bilder betrachten

Ein Bild kann angesehen werden wie in Kapitel Inhalte ansehen beschrieben. Zudem kann im Menü Datei die Funktion Diashow aufgerufen werden. Damit öffnet sich ein neuer Aktenreiter (Tab) im Browser, der die im aktuellen Ordner befindlichen Bilder als Diashow anzeigt.

Die zuvor erwähnte Diashow-Funktion kann auch direkt auf Ordner der Dateiverwaltung der WebBox angewendet werden. Dazu wird die Diashow-Funktion zunächst eingeschaltet, indem der Punkt Diashow einschalten im Menü gewählt wird. Damit wird die standardmäßig ausgeschaltete Diashow-Funktion aktiviert. Anschließend wird ein Ordner geöffnet, der Bilder enthält. Mit Klick auf eines der Bilder wird die Diashow direkt aus dem Ordner heraus gestartet.

Sollen Bilder wieder als Dateien in der Dateiverwaltung behandelt werden, beispielweise zum Markieren einzelner Bilddateien, wird die Funktion Diashow ausschalten im Menü gewählt. Damit wird die Diashow-Funktion ausgeschaltet.

4.7.2. Bilder öffentlich zugänglich machen

Die Diashow-Funktion der WebBox läßt sich auch aus der öffentlichen Ablage heraus verwenden. Es genügt, einen Ordner mit Bilddateien in den Ordner Öffentlich zu legen um die betreffenden Bilder mit allen zu teilen, die den Namen des Ordners kennen. Der URL zur Diashow ergibt sich aus der Adressleiste des Browsers mit Aufruf der Funktion Diashow aus dem Menü Datei.

Beispiel

Ein Ordner mit Bilddateien namens 1234567 liegt im Ordner Öffentlich/bilder des Benutzers fred. Diese Bilder können dann über den folgenden URL als Diashow betrachtet werden

http://localhost:8089/file-cms/fotos/?o=fred/bilder/1234567

Kombiniert mit der WebDAV-Funktion können z.B. Fotos vom Mobilgerät in wenigen Schritten zentral zugänglich gemacht werden.

4.8. Produktive Nutzung

Ist eine WebBox abgesichert, wie in WebBox sichern beschrieben, kann sie von überallher verwendet werden. Wir gehen für die weitere Beschreibung hier einmal von der Betriebsart hinter einem Proxy aus.

Zur Erreichbarkeit 'von außen' ist mindestens die Kenntnis der IP-Adresse des Routers zum Internt erforderlich, hinter dem die WebBox läuft. Besser ist es aber, bei einem entsprechenden Anbieter eine Domain wie etwa example.com zu registrieren und diese auf die IP-Adresse des Routers verweisen zu lassen. Für wechselnde IP-Adressen, wie sie bei heimischen Internet-Anschlüssen vorkommen, kann ein Anbieter für dynamisches DNS eingeschaltet werden.

Sind Domain und dynamisches DNS geschaltet, muss im Router der Port 443 für die Kommunikation über HTTPS geöffnet und eine Weiterleitung dieser Anfragen an den Proxy geschaltet werden.

5. Eigene Konfiguration

Voraussetzungen für die Nutzung der WebBox sind das Installationspaket der WebBox sowie Java, Tomcat und Derby. Diese Bestandteile werden bei der Installation geladen, sie können aber auch einzeln beschafft und zusammengebaut oder aus vorhandenen Beständen genutzt werden.

Dies wird hier beispielhaft im Home-Verzeichnis des Benutzers ausgeführt. Auf einem Linux-System sind Benutzerverzeichnisse im Pfad /home angelegt, sie werden deshalb auch Home-Verzeichnis genannt. Das Home-Verzeichnis eines Benutzers namens fred ist zum Beispiel /home/fred.

5.1. Beschaffung

Alle Teile sind als Freie Software erhältlich. Die noch nicht auf der Zielmaschine vorhandenen Teile können von ihren Produktseiten im Internet heruntergeladen werden:

Die heruntergeladenen Dateien finden sich anschließend je nach Konfiguration des Browsers üblicherweise in /home/fred/Downloads, je nach ausgewählter Version unter Namen wie etwa

  • Java: zulu11.43.55-ca-jre11.0.9.1-linux_x64.tar.gz

  • Tomcat: apache-tomcat-9.0.41.tar.gz

  • Derby: db-derby-10.15.2.0-bin.tar.gz

  • WebBox: wbx-3-dist.tar.xz

Diese Dateien werden wie folgt entpackt:

Kommandos zum Entpacken der Bestandteile einer WebBox
cd /home/fred
mkdir -p wbx-inst/{java,tc,db,wbx}
cd Downloads
tar -xf zulu11.43.55-ca-jre11.0.9.1-linux_x64.tar.gz -C ../wbx-inst/java --strip 1
tar -xf apache-tomcat-9.0.41.tar.gz -C ../wbx-inst/tc --strip 1
tar -xf db-derby-10.15.2.0-bin.tar.gz -C ../wbx-inst/db --strip 1
tar -xf wbx-3-dist.tar.xz -C ../wbx-inst/wbx --strip 1

Damit sind die benötigten Programme bereit zur Verwendung. Der Ordner /home/fred/wbx-inst/wbx wird für den Rest dieses Dokuments $WBX-INST genannt. Im nächsten Abschnitt ist beschrieben, wie die WebBox zur Nutzung konfiguriert wird.

5.2. Zusammenbau

Die WebBox ist standardmäßig so eingerichtet, wie es in Installation und Programme bündeln beschrieben ist. Die von der WebBox benötigten Programme Java, Tomcat und Derby können aber auch anders eingebunden werden.

5.2.1. Vorhandene Programme verwenden

Sind Java, Tomcat und Derby bereits vor der Installation der WebBox auf der Maschine vorhanden, ist in der Regel bei deren Installation ein systemweiter Pfadeintrag für JAVA_HOME, CATALINA_HOME oder DERBY_HOME gemacht worden. In diesen Fällen können die so vorliegenden Programme von der WebBox mitgenutzt werden. Die Pfadangabe im Start- / Stoppskript der WebBox kann dann auskommentiert bleiben, wie es im Auslieferungszustand der WebBox enthalten ist.

Auslieferungszustand der WebBox: Die Ablageorte von Java, Tomcat und Derby sind auskommentiert
# export JAVA_HOME=
# export CATALINA_HOME=
# export DERBY_HOME=

Diese Betriebsart entspricht der Anordnung gemäß folgendem Schaubild.

WebBox
Abb. 6. die WebBox mit vorhandenen Programmen
Programme von anderer Stelle einbinden

Sollen Teile der für die WebBox erforderlichen Ablaufumgebung anders eingebunden sein, müssen die Pfade zu Java, Tomcat und Derby im Start- und Stoppskript, der Datei $WBX-INST/wbx, eingetragen werden wie im folgenden Beispiel.

Beispiel für die Angabe individueller Ablageorte von Java, Tomcat und Derby
export JAVA_HOME=/home/fred/wbx-inst/java
export CATALINA_HOME=/home/fred/wbx-inst/tc
export DERBY_HOME=/home/fred/wbx-inst/db

5.2.2. Programme bündeln

Eine weitere Variante ist es, Java, Tomcat und Derby in den Ordner der WebBox zu kopieren und mit der WebBox zu bündeln. Die dafür vorgesehenen Ordner sind

  • $WBX-INST/.conf/prg/java

  • $WBX-INST/.conf/prg/tc-home (nur CATLAINA_HOME/bin und CATLAINA_HOME/lib)

  • $WBX-INST/.conf/prg/derby (nur lib)

Werden Java, Tomcat und Derby in die obigen Ordner der WebBox kopiert, kann das Start- / Stoppskript der WebBox im Auslieferungszustand belassen werden, mit auskommentierten Pfadangaben wie in Vorhandene Programme verwenden. Die Nutzung der WebBox kann dann mit allen Bestandteilen aus einem Ordner heraus erfolgen wie im folgenden Schaubild.

WebBox
Abb. 7. die WebBox mit gebündelten Programmen

In dieser Variante lässt sich die WebBox mit allen Bestandteilen und Daten einfach transportieren. Es muss stets nur der WebBox-Ordner kopiert werden.

5.3. Daten und Apps

Die Ablageorte für Daten und Apps sind standardmäßig auf die Ordner $WBX-INST/data und $WBX-INST/apps festgelegt. Sie können auf einen beliebigen anderen Ort umgestellt werden, indem im Start- und Stoppskript, der Datei $WBX-INST/wbx, die Einträge der Umgebungsvariablen WBX_DATA und WBX_APPS entsprechend geändert werden.

Diese Angaben werden zudem als Java-Systemvariablen wbx.data und wbx.apps an Tomcat weitergereicht. Auf diese Weise können sie 'von außen' auch dem Java-Prozess von Tomcat und allen Webapps übermittelt werden. Ein auf der WebBox laufendes Java-Programm kann die Pfade zu den Daten und Apps der WebBox mit System.getProperty("wbx.data") und System.getProperty("wbx.apps") ermitteln.

6. Technische Infos

Die WebBox kombiniert die folgendenden Einzelkomponenten zu einer ausführbaren Einheit.

  • Java (Virtuelle Maschine und Ablaufumgebung)

  • Tomcat (Web- und Applikationsserver)

  • Derby (relationales Datenbanksystem)

  • WebBox Konfiguration

    • Nutzerverwaltung

      • Nutzerdatenbank

    • Dateiverwaltung

    • Datenablage

    • Root App

    • WebBox Lib

Die Konfiguration dieser Komponenten ist nachfolgend beschrieben.

6.1. Ordnerstruktur

Eine WebBox besitzt die folgende Struktur.

wbx ............... eine WebBox

  apps ............ Webanwendungen der WebBox-Nutzer
    ROOT .......... Startseite der WebBox
    jslib ......... zentrale JavaScript-Bibliotheken
    fonts ......... zentrale Schriftarten
    um ............ Nutzerverwaltung
    file-cms ...... Dateiverwaltung

  data ............ WebBox Datenablage
    db ............ relationale Datenbanken (von Derby verwaltet)
      udb ......... WebBox Nutzer und Rollen
    home .......... private Daten
    www ........... oeffentliche Daten
    logs .......... Logs
    tc-work ....... Tomcat Cache
    tc-temp ....... Temp-Verzeichnis für Webapps

  .conf ........... interne Inhalte der WebBox
    bin ........... WebBox-Skripte
    prg ........... WebBox-Software
      derby ....... Derby (optional)
      java ........ Java (optional)
      tc-home ..... Tomcat CATALINA_HOME (optional)
        bin ....... Tomcat-Skripte
        conf ...... leer/ungenutzt
        lib ....... Tomcat-Bibliotheken
        logs ...... leer/ungenutzt
        temp ...... leer/ungenutzt
        webapps ... leer/ungenutzt
        work ...... leer/ungenutzt
      tc-base ..... WebBox CATALINA_BASE
        bin ....... nur tomcat-juli.jar
        conf ...... Tomcat-Konfiguration für die WebBox
        lib ....... Bibliotheken für die WebBox
        logs ...... leer/ungenutzt
        temp ...... leer/ungenutzt
        webapps ... leer/ungenutzt
        work ...... leer/ungenutzt

Der Ordner data ist für veränderliche Daten des Nutzers vorgesehen, die Konfiguration ist in Datenablage näher erläutert.

6.2. Java

An der Konfiguration von Java macht die WebBox keine Änderungen.

6.3. Tomcat

Die Konfiguration von Tomcat wurde für die WebBox angepasst und befindet sich in $WBX-INST/.conf/prg/tc-base. Die folgenden Änderungen an der Standardkonfiguration von Tomcat wurden unternommen.

Port

Der Port der WebBox ist in der Datei $WBX-INST/.conf/prg/tc-base/conf/server.xml eingestellt. Dort ist im Element Connector das Attribut port standardmäßig auf 8089 gesetzt. An dieser Stelle kann ohne Auswirkung auf die Konfiguration der WebBox ein beliebiger anderer Port eingetragen werden.

JarScanner

In $WBX-INST/.conf/prg/tc-base/conf/context.xml wurde der Eintrag <JarScanner scanManifest="false"/> hinzugefügt (Quelle: http://www.skybert.net/java/tomcat-fails-to-scan-jar-file-that-i-never-asked-for/ ).

Datenbanktreiber

Zur Verwendung von Derby Datenbanken über den ClientDriver müssen ab Derby 10.15 die folgenden JARs im Classpath sein: derbyclient.jar, derbyshared.jar und derbytools.jar. Diese sind in $WBX-INST/.conf/prg/tc-base/lib abgelegt.

Ablageort der Log-Dateien

In der Datei $WBX-INST/.conf/prg/tc-base/conf/logging.properties wurden die Ablageorte für Log-Dateien auf das Verzeichnis ${wbx.data}/logs umgestellt. In $WBX-INST/.conf/prg/tc-base/conf/server.xml wurde das Attribut directory für das AccessLogValve auf den Ordner ${wbx.data}/logs umgestellt.

Ablageort für Apps

In $WBX-INST/.conf/prg/tc-base/conf/server.xml wurde das Attribut appBase für den Host localhost auf ${wbx.apps} umgestellt.

Tomcat Work-Ordner

In $WBX-INST/.conf/prg/tc-base/conf/server.xml wurde im Element Host der Engine Catalina das Attribut workDir hinzugefügt. Es verweist auf ${wbx.data}/tc-work/Catalina, damit nicht ins CATALINA_BASE-Verzeichnis geschrieben wird.

Kontexte data und home

In $WBX-INST/.conf/prg/tc-base/conf/Catalina/localhost wurden die Dateien data.xml und home.xml angelegt. Sie verweisen auf ${wbx.data}/www sowie ${wbx.data}/home und sorgen so dafür, dass Tomcat die Inhalte dieser beiden Datenverzeichnisse ausgibt. Deren Anlage beschreibt das Kapitel Dateiverwaltung. Ihre Konfiguration ist im Kapitel Datenablage beschrieben.

Single Sign-On

In $WBX-INST/.conf/prg/tc-base/conf/server.xml wurde das SingleSignOn valve eingeschaltet. Eine Benutzeranmeldung wirkt über alle Webanwendungen der WebBox hinweg.

6.3.1. Tomcat verkleinern

Das Installationspaket von Tomcat ist mehr als 16 MB groß. Für die WebBox ist nur der Inhalt in den Ordnern bin und lib erforderlich. Diese beiden Ordner allein erfordern nur 10 MB. Verzichtet man auch auf Java Server Pages (JSP), lässt sich Tomcat auf 4,8 MB verkleinern.

Beim Verzicht auf JSP können alle Klassenbibliotheken weggelassen werden ausser den folgenden:

Tomcat-Ordner lib

annotations-api.jar, catalina.jar, catalina-ant.jar, jaspic-api.jar, serlet-api.jar, tomcat-api.jar, tomcat-coyote.jar, tomcat-dbcp.jar, tomcat-jdbc.jar, tomcat-jni.jar, tomcat-util-scan.jar

JSP ausschalten

Wenn JSP weggelassen werden, müssen diese in der Datei $WBX-INST/.conf/prg/tc-base/conf/web.xml deaktiviert werden. Dazu wird das JSP-Servlet und das JSP-Servlet-Mapping auskommentiert, damit die fehlenden JSP-Bibliotheken nicht zu Abbrüchen beim Start des Servers führen.

6.4. Derby

Mit dem Start der WebBox wird ein Derby Network Server auf Port 1528 gestartet. Der Port kann im Startskript, der Datei $WBX-INST/.conf/bin/dns, in der Variablen DERBY_PORT geändert werden.

Ein geänderter Port für Derby muss auch allen Anwendungen bekannt gegeben werden, die eine Datenbank benutzen. Im Auslieferungszustand der WebBox betrifft das

  • Tomcat, Element GlobalNamingResources in der Datei $WBX-INST/.conf/prg/tc-base/conf/server.xml

  • die Nutzerverwaltung, Datei $WBX-INST/apps/um/META-INF/context.xml

Die oben erwähnte Datei context.xml der Nutzerverwaltung ist ein Beispiel für das Einbinden einer Derby-Datenbank in andere Webanwendungen, die auf der WebBox laufen. Webanwendungen können mit META-INF/context.xml eine JDBC-Datenquelle deklarieren und müssen damit im Programmcode nur den Namen der Datenquelle laut Attribut name verwenden. Einzelheiten der Konfiguration werden so wirksam aus dem Programmcode ferngehalten.

Die Verwendung von Derby-Datenbanken in Java-Programmen ist beispielsweise in der Dokumentation von BaseLink beschrieben.

6.5. Nutzerverwaltung

Die Nutzerverwaltung ist ein zentraler Bestandteil der WebBox, der Hand in Hand mit der Container Managed Security des Servlet Containers geht. Die WebBox ist in diesem Punkt konform mit der Java-Spezifikation: Webanwendungen auf der Grundlage der Java-Spezifikation können die Authentifizierung und Autorisierung der WebBox nahtlos einbinden.

Für die WebBox werden Benutzer und Rollen über eine mitgelieferte Webanwendung in einer relationalen Datenbank gespeichert und verwaltet. Die Konfiguration zur Verwendung der Nutzerdatenbank ist in der Anleitung beschrieben und so wie dort beschrieben in der Konfiguration der WebBox im Ordner .conf/prg/tc-base/conf eingerichtet.

Die Kennworte von Benutzern werden in der Nutzerdatenbank der WebBox verschlüsselt gespeichert. Sie können bei Einblick in die Datenbank nicht im Klartext gelesen werden.

6.6. Datenablage

In $WBX-INST/data/home liegen Daten, die die WebBox nur an den angemeldeten Benutzer ausgibt. Der Ordner $WBX-INST/data/www enthält öffentliche Daten, die von der WebBox als öffentliche Inhalte ohne Einschränkung ausgeliefert werden. Die Einstellungen hierfür sind in den in ihnen befindlichen Ordnern namens WEB-INF konfiguriert. Diese sind in der Dateiverwaltung der WebBox nicht sichtbar. Ihr Name oder Inhalt darf nicht verändert werden.

Die Datenablage kann allerdings so wie sie ist an einen beliebigen anderen Ort verschoben werden. Der neue Ablageort muss dann in der Konfiguration der WebBox vermerkt werden, wie in Daten und Apps beschrieben.

6.7. WebBox Startseite

Die Startseite der WebBox befindet sich im Ordner $WBX-INST/apps/ROOT. Sie kann beliebig geändert werden.

6.8. Dateiverwaltung

Die Dateiverwaltung der WebBox ist eine Java-Webanwendung und befindet sich im Ordner $WBX-INST/apps/file-cms. Die Dateiverwaltung ist speziell für die Verwaltung der Inhalte der WebBox-Datenablage via Browser ausgelegt und vorkonfiguriert. Sie kann zudem prinzipiell mit beliebigen Datei-Systemen verwendet werden.

Ihr Quellcode und weitere Informationen sind im Code Repository enthalten.

6.9. WebBox Lib

Die Datei wb-lib.jar im Ordner $WBX-INST/.conf/tc-base/lib enthält Java-Klassen, die für die Ausgabe von Inhalten der WebBox-Datenablage wichtig sind. Weitere Informationen und ihr Quellcode ist im Code Repository enthalten.

6.10. WebBox erweitern

Die WebBox kann mit Webanwendungen erweitert werden, die der Java Servlet Spezifikation folgen. Solche Webanwendungen werden gewöhnlich als Dateien mit Endung .war für web archive ausgeliefert. Eine .war-Datei wird einfach in den Ordner $WBX-INST/apps gelegt, um die Webanwendung mit der WebBox auszuführen. Wird beispielsweise die Datei meine-app.war so installiert, ist sie aufrufbar mit

http://localhost:8089/meine-app/

Erfordert die App eine Datenbank, wird gewöhnlich die Java Database Connectivity (JDBC) eingesetzt. Die App kann dann das Datenbanksystem der WebBox verwenden wie im Kapitel Derby beschrieben.

6.10.1. Statische Webseiten

Auf ähnliche Weise können auch statische Inhalte wie HTML-Seiten, Bilder oder Javscript-Programme genutzt werden. Im einfachsten Fall wird ein neuer Ordner im Ordner $WBX-INST/apps erstellt und die betreffenden Inhalte dort hineingelegt. Wird zum Beispiel ein neuer Ordner mein-webinhalt mit einer Datei index.html darin in den Order $WBX-INST/apps gelegt, ist der Inhalt anschließend aufrufbar mit

http://localhost:8089/mein-webinhalt/

Auf dieselbe Weise funktionieren statische Inhalte, die in den Ordner $WBX-INST/data/www gelegt werden. Hier ist allerdings der Unterschied, dass sie dort auch mit der Dateiverwaltung der WebBox verwendet werden können.

7. Dokumenthistorie

Tabelle 2. Änderungen
Nr Datum Autor Beschreibung

1

9. Mai 2020

Ulrich

Erste Anlage der Version 3 der WebBox

2

28. Dezember 2020 - 10. Januar 2021

Ulrich

Neue Dokumentation Version 3