#+OPTIONS: ^:nil

#+CAPTION: Plauna Banner [[./docs/resources/plauna-hero-banner.png]]

Organize your e-mails without sacrificing your privacy

Plauna is a privacy focused service that helps you categorize your e-mails. All of its data is stored only on your computer.

You can parse your e-mails from mbox files or directly by connecting to your IMAP servers. Plauna helps you categorize your e-mails and automates the process so that incoming e-mails are moved to their respective folders on your IMAP server.

IMPORTANT: Plauna is still under heavy development at the moment. The features are subject to change.

• Features

• You own 100% of your data. Everything is on your machine.

• You define your categories: Use as many or few as you like

• Multi-language support.

• Support for multiple IMAP connections.

• Statistics about your emails and metadata (very basic, still under development).

• Upload data from mbox archives.

• Read emails directly from IMAP folders.

• What Plauna is NOT

Plauna is not an e-mail archive tool. It only saves headers and contents from e-mail that it thinks will be useful for categorizing your e-mails. Certain things like the attachments are explicitly not stored in order to save db space. Please do no rely on Plauna to successfully preserve the e-mails you want to archive.

• How to get Plauna

** Docker

The easiest way to get Plauna is using the [[https://hub.docker.com/r/ozangulle/plauna][Docker image]].

Plauna requires some configuration to work as mention under "How to use" -> "How to run" below. If you're going to use docker, it makes sense to mount the configuration file in a separate volume.

** Build from source The second way to get Plauna is fetching it from the git repository and compiling using Clojure CLI with the command:

#+begin_src clj -T:build uber #+end_src

This will produce a Plauna uberjar in the ./target directory which you can run using a Java Runtime Environment.

• Security

Plauna comes without security features like different users. It is made to be used by self-hosters who own and use the service themselves in an internal network that is isolated.

Please do not use Plauna in an open network or open ports to outside!

• How to use

** Configuration

There are two configuration values which cannot be configured from withing Plauna. These are:

The database folder - this is where the database file (SQLITE) and the training files live. Defaults to /var/lib/plauna The server port - Defaults to 8080

Note: If you run Plauna as a Docker container, the directory /var/lib/plauna is created automatically. If you want to run it on your computer as a jar file, you must create this directory yourself.

*** Environment Variables

You can use the environment variables $DATA_FOLDER and $SERVER_PORT

*** CLI Parameters

You can also configure these values using the cli parameters --data-folder, and --server-port.

E.g. java -jar plauna.jar --server-port 80

*** Order of Priority

In case multiple values are provided, plauna decides on which value to use according to the priority list below:

1. CLI parameters
2. Environment variables
3. Default configuration

** Authentication

Plauna supports basic (username - password) and oauth2 (XOAUTH2) authentication methods.

**** Basic Authentication

Basic authentication is very straightforward. Leave "Authentication" at "Basic" (it is the default value), enter your username and password. You will need to click at "Connect" on the "Connections" page in order to connect to the server. This is only needed during the initial set up. Plauna automatically tries to connect to every configured e-mail server on startup.

**** Oauth2

Currently only tested for Gmail!

Prerequisites: You need your own application on Google Cloud, or Azure, or whatever e-mail provider you are using.

When you select "Oauth2" on the connection screen, a new section called "Auth Providers" will appear underneath the connection details. You need to fill in a name (only for displaying on Plauna, you can choose whatever you like), the authentication and the token urls of your oauth provider, the client id and secret of your application, the scopes (separated with an empty space), and a redirect url. The redirect url path is "/oauth2/callback". If you're testing on localhost, you need to enter http:///localhost:{port}/oauth2/callback. If you are using a custom domain for Plauna, please adjust accordingly.

After saving the auth provider, you need to select it under connection config and click "update connection". You can leave the "Secret" field in the "Connection Config" form empty. It will not be used for oauth2.

After you set up your configuration, go to the "Connections" page and click on "Connect". On your first login, you will be redirected to your oauth provider in order to authorize the application you created to access your data. If everything is set up correctly, you will then be redirected automatically back to Plauna.

** Getting Started

When you start Plauna, it starts a web server on the port which you specified (defaults to 8080) and connects to the IMAP servers that you configured. You can use Plauna without configuring any IMAP servers but you would be missing out on the "move e-mail" functionality. On your very first start, the database is empty. You need to fill it with e-mails. There are three non-exclusive ways of doing this:

1. Go to "Admin". Under the header "Parse E-mails" select an mbox file and click on the button "Parse Mbox". You can see your e-mails under the "E-mails" tab shortly thereafter.

2. Go to "Watchers", click on any IMAP account name, select a folder you want to parse the e-mails in, make sure "Move e-mails after categorization" is unchecked and click on the button "Parse E-mails". This will read all the e-mails in the selected folder.

3. Just leave Plauna running and watch it save your e-mails. Beware: Depending on how many e-mails you receive on any given day, this method may be very slow.

** Language Detection

Plauna automatically detects the language of an e-mail upon parsing it. Here, you must also select the languages that you want to use in training - therefore the languages you want to use in categorization.

** Categorization

*** Create Categories

Go to "Admin" -> "Manage Categories" in order to create and delete categories. If you set up connections to your IMAP servers in your settings file, anytime you create a category Plauna will try to create a folder on the servers. If you however delete a category, Plauna will not delete it on the server. As a general rule, Plauna reads and moves e-mails as well as it creates folders but it never deletes anything.

*** Categorize E-mails

Under the tab "E-mails" you can edit the language and category of every e-mail; either as a batch operation or by clicking on an e-mail and changing it at the details page.

#+CAPTION: List emails and edit metadata [[./docs/resources/plauna-new-1.png]]

#+CAPTION: See details of an email and edit metadata [[./docs/resources/plauna-new-2.png]]

*** Data Training

Under the tab "E-mails" there is an expandable section called "Data Training". Click on the button "Train with Existing Data" to train the model(s) using the existing categorized data. Important: You must have more than one category saved for each language you want to train in.

You must have selected at least one language in "Admin" -> "Manage Languages" in order to start training on your e-mails.

*** Automatic Categorization

After training your models on the categories you created, Plauna will categorize each e-mail you receive and moved it automatically to its corresponding folder.

• Debugging

Plauna comes with a built-in REPL that can be activated on the administration page. It is hard-coded to listen to port 7888. If you know your way around Clojure and the codebase, you can use it to inspect the current state of the application or even make changes while it's running. Be aware that all your changes will be lost when you restart the application. If you are not debugging or do not know how to use the Clojure REPL, there is absolutely no reason to start it. There are no further features hidden behind it.