Stephan Richter
3 years ago
3 changed files with 123 additions and 1 deletions
@ -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 |
@ -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 |
Loading…
Reference in new issue