From 5627d96f2a26e1a88092a8a3de6ef63e67f7fc7b Mon Sep 17 00:00:00 2001
From: finga <finga@onders.org>
Date: Thu, 16 Feb 2023 15:53:18 +0100
Subject: [PATCH] readme: Add documentation to the readme [CI SKIP]

Explain and document the project and (hopefully) all necessary steps
to get it running.
---
 README.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 103 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5d3a5a0..20505dd 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,105 @@
 # remindrs
 
-Send an email at a given time containing a certain title and message.
+Send an email at a given time. The basic purpose of remindrs is to
+send a reminder email containing a certain title and message.
+
+## Setup
+
+There are two basic steps to install remindrs. First it is recomended
+to prepare the Database and then build the binary or build and install
+the Debian package.
+
+### Database
+
+Prepare an empty Postgres database preferably with an extra user.
+
+### Building
+
+Remindrs can be built in two ways. By using the classic Rust
+toolchain to build a binary. And by using
+[`cargo-deb`](https://github.com/kornelski/cargo-deb) to build a
+Debian package.
+
+For both ways a Postgres database is mandatory.
+
+#### With the Rust toolchain
+
+In order to build just the remindrs binary with the standard Rust
+toolchain build it with cargo:
+
+```sh
+cargo build
+```
+
+#### Debian package
+
+In order to build the remindrs Debian package use
+[`cargo-deb`](https://github.com/kornelski/cargo-deb):
+
+```sh
+cargo deb
+```
+
+The generated Debian package also installs a systemd service unit, but
+does not enable it by default.
+
+#### Configuraion
+
+To configure remindrs the following configuration options are
+available. When remindrs is started it tries to load the configuration
+either from the path passed as the command line argument
+`-c`/`--config`, or by the default paths. Those are `./config.toml`,
+`$XDG_CONFIG_HOME/remindrs/config.toml` or
+`$HOME/.config/remindrs/config.toml` if `$XDG_CONFIG_HOME` is not set,
+and finally `/etc/remindrs/config.toml`.
+
+Note that all options commented out have the given parameter as a
+default value and are not mandatory.
+
+```
+[database]
+# host = "localhost"
+# port = 5432
+# name = "remindrs"
+# user = "remindrs"
+pass = "remindrs"
+
+# [server]
+# address = "::1"
+# port = 8080
+
+# [email]
+# from = "remindrs@localhost"
+```
+
+## Usage
+
+The configuration is mostly done via the configuration file. When
+remindrs is running the only way to interact with it is via the API.
+
+### Command line arguments
+
+The binary supports only a small set of command line arguments.
+
+```
+Usage: remindrs [OPTIONS]
+
+Options:
+  -c, --config <FILE>      Use a custom config file
+  -l, --log-level <LEVEL>  Set a log level [default: INFO]
+  -h, --help               Print help
+  -V, --version            Print version
+```
+
+### API
+
+In order to create a reminder send a `POST` request to the API
+endpoint.
+
+For example `curl` can be used like the following:
+
+```sh
+curl -X POST localhost:8080/v1/reminder \
+  -H 'Content-Type: application/json'   \
+  -d '{"planned":"2023-02-02T14:16:00.000000000+07:00", "title":"test title", "message":"test message", "receiver":"user@localhost"}'
+```