Browse Source

added doc

drop_old_mail
Stephan Richter 3 years ago
parent
commit
d3c27d063e
  1. 37
      README.md
  2. 85
      doc/instructions.md
  3. 2
      pom.xml

37
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

85
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

2
pom.xml

@ -6,7 +6,7 @@
<groupId>org.example</groupId> <groupId>org.example</groupId>
<artifactId>Widerhall</artifactId> <artifactId>Widerhall</artifactId>
<version>0.2.24</version> <version>0.2.25</version>
<build> <build>
<plugins> <plugins>
<plugin> <plugin>

Loading…
Cancel
Save