updated README

Signed-off-by: Stephan Richter <s.richter@srsoftware.de>

README.md

@@ -1,3 +1,42 @@
+# Willkommen bei Widerhall!
+
+(english version below)
+
+## Was ist Widerhall?
+
+Diese Software zielt darauf ab, _Mailing-Listen_ zu erstellen, ohne sich mit dem Thema _Mail-Server_ beschäftigen zu müssen.
+
+Alles was du brauchst, um mit _Widerhall_ eine Mailing-Liste zu erstellen ist diese Software und eine IMAP-fähige Email-Adresse.
+
+## Wie funktioniert das?
+
+Nach dem Start der Software geht man auf deren Startseite und legt einen Administrations-Account an.
+
+Dann kann man – als Admin – Mailing-Listen anlegen, indem man einfach die Zugangsdaten zu den entsprechenden Mail-Adressen in dieser Software hinterlegt.
+
+Sobald man eine so angelegte Verteiler-Liste aktiviert, verbindet sich diese Software mit der entsprechenden Mailbox und wartet auf eingehende Nachrichten. Immer wenn eine Nachricht empfangen wird, wird diese an die jeweiligen Abonnenten der Liste weitergeleitet.
+
+## Wie kann die Mailing-Liste abonniert werden?
+
+Du kannst jede Mailing-Liste, welche du angelegt hast, öffentlich machen.
+Alle öffentlichen Mailing-Listen werden auf der Startseite von _Widerhall_ aufgelistet. Besucher dieser Seite können dann jede beliebige der öffentlichen Mailing-Listen abonnieren, indem sie den **abonnieren**-Button klicken. Sie müssen dann ihren Namen und ihre Email-Adresse angeben. Danach bekommen Sie eine Email mit einem Link, den sie einmalig anklicken müssen, um ihr Abonnement zu bestätigen.
+
+## Kostet es was?
+
+Nein. _Widerhall_ ist FOSS. Das steht für Free Open Source Software – freie, quelloffene Software – und bedeutet jeder kann eine Kopie des Software-Codes beziehen und es selbstverantwortlich einsetzen.
+
+## Anleitung
+
+Lesen Sie die [Anleitung] für Hinweise zu Installation und Wartung.
+
+## aktueller Status
+
+Auch wenn diese Software schon einige Zeit für die Verteiler-Listen des Jenaer Reparier-Cafes verwendet wird, gibt es keine Garantie. Die Software könnte Fehler enthalten. Betrachten Sie die aktuelle Version als Beta.
+
+[Anleitung]: doc/anleitung.md
+
+-------
+
 # Welcome to Widerhall!
 
 ## What is Widerhall?

doc/anleitung.md

@@ -0,0 +1,85 @@
+# Installation
+
+## Docker
+
+Die einfachste Art, Widerhall einzusetzen, ist Docker zu verwenden.
+
+Wenn du Docker schon am Laufen hast musst du nur noch folgendes tun:
+
+1. [Dockerfile](../Dockerfile) herunterladen
+2. Image erstellen: `docker build -t widerhall /path-to-dockerfile/`
+3. Container starten:
+
+```bash
+docker run \
+    --name widerhall \
+    -d widerhall
+```
+
+Danach solltest du zu http://<your machine>/ navigieren können.
+
+### Konfiguration, Daten-Persistenz
+
+Um Daten über Computer/Docker-Neustarts hinaus zu erhalten, muss ein _Volume_ in den Container eingebunden werden:
+
+```bash
+docker run \
+    --name widerhall \
+    -v /some/directory:/data
+    -d widerhall
+```
+
+_Widerhall_ wird alle zu speichernden Daten in `/data`, also dem eingebundenen Speicher, ablegen.
+
+* `widerhall.sqlite3` – dies ist die Haupt-Datenbank-Datei. Passen Sie gut darauf auf!
+* `widerhall.config.json` – dies ist die Haupt-Konfigurations-Datei. Dort können Sie die vorgegebenen Einstellungen überschreiben.
+* `archive` – Hier werden gespeicherte Emails abgelegt.
+
+Diese Dateien/Verzeichnisse werden beim ersten Start (oder wenn Sie zwischenzeitlich gelöscht wurden) angelegt.
+
+Die Konfiguration ist wie folgt aufgebaut:
+
+```json
+{
+  "port":80,
+  "base_url":"https://widerhall.srsoftware.de",
+  "locations":{
+    "database":"/data/widerhall.sqlite3",
+    "configuration":"/data/widerhall.config.json",
+    "archive":"/data/archive",
+    "base":"/Widerhall"
+  }
+}
+```
+
+* Die `base_url` sollte so angepasst werden, dass sie Ihren Server-Einstellungen entspricht.
+* Falls Sie die Datenbankdatei an einem anderen Ort speichern wollen, ändern Sie den `database`-Eintrag.
+* Wenn Sie die `configuration`-Einstellung überschreiben, wird _Widerhall_ seine Konfiguration ersetzen mit der Datei, die an der angegebenen Stelle gefunden wird.
+* Falls das Mail-Archiv an einem anderen Ort gespeichert werden soll, kann der `archive`-Eintrag angepasst werden.
+* `base` sollte auf das Installations-Verzeichnis von _Widerhall_ zeigen. Standardmäßig ist das  _/Widerhall_.
+
+### SSL termination
+
+_Widerhall_ versucht alles einfach zu halten. Der eingebaute Webserver hat keine Ahnung von SSL. 
+Wenn Sie die Website sicher betreiben wollen, lassen Sie _Widerhall_ hintereinem **reverse proxy**, wie z.B. [nginx_proxy] laufen.
+
+## Maven
+
+_Widerhall_ ist ein Java-Project, welches mit Apache Maven gebaut werden kann.
+Fall Sie eine aktuelle Java-Installation (Java 17+) und Maven auf Ihrem System haben, sollten Sie _Widerhall_ wie folgt compilieren können:
+
+1. Holen Sie sich den Programm-Code: `git clone https://git.srsoftware.de/StephanRichter/Widerhall.git`
+2. Wechseln Sie ins heruntergeladene Verzeichnis: `cd Widerhall`
+3. Erzeugen Sie das ausführbare JAR-Archiv: `mvn clean test compile assembly:single`
+4. Starten Sie das JAR: `java -jar target/*.jar`
+
+# Übersetzungen
+
+Die Übersetzungen von _Widerhall_ werden als Branches des Quellcodes gepflegt:
+
+* _main_-Branch: english
+* _lang_de_-Branch: deutsch
+
+Einfach die Sprache Ihrer Wahl auschecken.
+
+[nginx_proxy]: https://github.com/nginx-proxy/nginx-proxy