From d3f5d89f7fafa6bbf4ab5e9a7a482288b32e00b4 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Tue, 24 Feb 2026 14:35:53 -0500 Subject: [PATCH] doc/README.rst: new reStructuredText README Mainly for Codeberg, but it's nice to have something in plain text regardless. --- doc/README.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 doc/README.rst diff --git a/doc/README.rst b/doc/README.rst new file mode 100644 index 0000000..b7d39c5 --- /dev/null +++ b/doc/README.rst @@ -0,0 +1,75 @@ +Overview +======== + +Managing an open source mail system with virtual users is difficult +because every piece of software maintains its own database of users, +domains, preferences, etc. + +If you're using a web interface to manage virtual users in a database, +what happens when you delete a user? Chances are, nothing: mail +directories are left on disk, webmail preferences are stored forever, +address books become orphaned. A related problem is that of renaming +an account. It's easy to move the user in one database, but then all +of the remaining filesystem directories and databases need to be +updated as well. (And quickly, on a running server.) + +Mailshears is designed to solve these problems, and currently does so +for the following projects: + +* `PostfixAdmin `_ + (user management) +* `Dovecot `_ (physical mail storage) +* `Roundcube `_ (webmail) +* `DAViCal `_ + (calendars and contacts) + + +Requirements +============ + +The main assumption we make is that your users are managed by +PostfixAdmin. Plugins exist for "Dovecot" (the filesystem), DAViCal, +and Roundcube, but they are all optional. + + +How it works +============ + +Each plugin knows how to do perform actions: + +* prune +* rename +* remove + +Depending on how you invoke mailshears, it figures out which plugins +need to be run, and then runs them in succession. + +By default, mailshears won't actually do anything. There's a variable +``i_mean_business: false`` in the config file that must be set to +``true`` before mailshears will modify the system. + + +Installation +============ + +Use *gem* from `RubyGems `_ to install the +release tarball: + +.. code-block:: console + + $ gem install mailshears-*.gem + Successfully installed mailshears-0.1.0 + Parsing documentation for mailshears-0.1.0 + Done installing documentation for mailshears after 0 seconds + 1 gem installed + +Afterwards, create a config by copying ``mailshears.example.conf.yml`` +to ``$XDG_CONFIG_HOME/mailshears/mailshears.conf.yml``, and then edit +it to fit your environment. + + +How to report bugs +================== + +Email them to me at michael@orlitzky.com, or report them on `Codeberg +`_. -- 2.51.0