From d3c27d063e54a268b33910fec98ad07cd5b90686 Mon Sep 17 00:00:00 2001
From: Stephan Richter <s.richter@srsoftware.de>
Date: Fri, 22 Apr 2022 20:17:47 +0200
Subject: [PATCH] added doc

---
 README.md           | 37 ++++++++++++++++++++
 doc/instructions.md | 85 +++++++++++++++++++++++++++++++++++++++++++++
 pom.xml             |  2 +-
 3 files changed, 123 insertions(+), 1 deletion(-)
 create mode 100644 README.md
 create mode 100644 doc/instructions.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bd69717
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# Welcome to Widerhall!
+
+## What is Widerhall?
+
+_Widerhall_ is the german word for reverberation. 
+
+This is a software dedicated to the creation of mailing lists without knowhow regarding _mailservers_.
+
+All you need to create a mailing list with _Widerhall_ is this software and an IMAP-enabled email address.
+
+## How does it work?
+
+After you started the software, you go to it's front page, set up an admin account.
+
+Then, as admin, you can create mailing lists by just entering the respective login credentials into this software.
+
+When enabling a list, this software connects to the respective mailbox and waits for incoming messages. Everytime a message is received, the software forwards it to any subscriber of that list.
+
+## How does subscription work?
+
+You can make public every mailing list you create.
+All public mailing lists are presented on _Widerhall_`s front page. Visitors may join each of the public mailing lists by hitting the _subscribe_ button. The need to enter their name and email address. After that, they receive a confirmation email with a link, that completes their subscription.
+
+## Is it free?
+
+Yes. _Widerhall_ is FOSS, which stands for Free Open Source Software.
+That means every on can obtain a free copy of the source code and use it on it`s own behalf.
+
+## Instructions
+
+Refer to [Instructions] for hints on setup and maintenance.
+
+## Current state
+
+This software is brand new and may contain bugs. Regard it as alpha state, do not use in production environments!
+
+[Instructions]: doc/instructions.md
\ No newline at end of file
diff --git a/doc/instructions.md b/doc/instructions.md
new file mode 100644
index 0000000..1e8839f
--- /dev/null
+++ b/doc/instructions.md
@@ -0,0 +1,85 @@
+# Installation
+
+## Docker
+
+Using docker is the easiest way!
+
+If you already have docker up and running, all you need to start Widerhall is
+
+1. Download the [Dockerfile](Dockerfile)
+2. Build the image: `docker build -t widerhall /path-to-dockerfile/
+3. Start a container:
+
+```bash
+docker run \
+    --name widerhall \
+    -d widerhall
+```
+
+You should now be able to go to http://<your machine>/
+
+### Configuration, data persistence
+
+To keep data after restarts of your container, you need to mount a volume into the container:
+
+```bash
+docker run \
+    --name widerhall \
+    -v /some/directory:/data
+    -d widerhall
+```
+
+Widerhall will create all persistent data in `/data`, resp. your volume:
+
+* `widerhall.sqlite3` – this is the main database file. Keep it warm, keep it safe.
+* `widerhall.config.json` – this is the main config file, where you can overload the default settings.
+* `archive` – Stored mails will end up here.
+
+Those files/directories will be created on the first start (or whenever you dropped them).
+
+The config is structured as follows:
+
+```json
+{
+  "port":80,
+  "base_url":"https://widerhall.srsoftware.de",
+  "locations":{
+    "database":"/data/widerhall.sqlite3",
+    "configuration":"/data/widerhall.config.json",
+    "archive":"/data/archive",
+    "base":"/Widerhall"
+  }
+}
+```
+
+* Alter the `base_url` to match your server settings.
+* If you want the database to be stored somewhere else, alter the `database` string.
+* If you change the `configuration` property, widerhall will overlaod it's configuation with whatever is found at the given location
+* If you want the archive to be stored somewhere else, alter the `archive` string.
+* `base` should point to the installation dir of Widerhall, which is _/Widerhall_ by default
+
+### SSL termination
+
+Widerhall tries to keep it simple. The built-in webserver does not know anything about SSL.
+If you want to keep a secure webiste, run _Widerhall_ behind a reverse proxy, such as [nginx_proxy].
+
+## Maven
+
+Widerhall is a Java project built with Apache Maven.
+If you have a recent installation of java (17) and maven on your system, you should be able to
+
+1. get the sources: `git clone https://git.srsoftware.de/StephanRichter/Widerhall.git`
+2. change to the downloaded dir: `cd Widerhall`
+3. build the runnable jar: `mvn clean test compile assembly:single`
+4. execute the jar: `java -jar target/*.jar`
+
+# Translations
+
+_Widerhall_`s translations are managed as branches of the source code:
+
+* _main_ branch: english
+* _lang_de_ branch: german
+
+Just checkout the language branch you want.
+
+[nginx_proxy]: https://github.com/nginx-proxy/nginx-proxy
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index e2772be..0443998 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
     <groupId>org.example</groupId>
     <artifactId>Widerhall</artifactId>
-    <version>0.2.24</version>
+    <version>0.2.25</version>
     <build>
         <plugins>
             <plugin>