added doc

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