Cypht¶

License: LGPLv2.1

This guide is tested with Cypht 2.8.0 on Uberspace 8.0.75. We can't guarantee it to work with newer versions.

Cypht is an open-source webmail client. You can use it to access multiple email accounts via any server or service that supports any of the following protocols: IMAP/SMTP, Exchange Web Services or JMAP.

Note

For this guide you should be familiar with the basic concepts of:

Prerequisites¶

We're using PHP version 8.4:

[isabell@moondust ~]$ uberspace tool version set php 8.4
OK: Set version of php to 8.4

Note

Cypht supports various methods for storing user settings. In this guide, we store them in the file system so that no database is required.

Installation (Part 1)¶

Create the cypht directory and download the software to this directory. Unzip the archive and then delete it afterwards. Use composer to install all dependencies (the command will take a while; don't worry). Then create the .env file.

[isabell@moondust ~]$ cd /var/www/virtual/$USER/
[isabell@moondust isabell]$ mkdir cypht
[isabell@moondust isabell]$ cd cypht/
[isabell@moondust cypht]$ wget "https://github.com/cypht-org/cypht/archive/refs/heads/master.zip" -O "master.zip"
[isabell@moondust cypht]$ bsdtar -xf master.zip --strip-components=1
[isabell@moondust cypht]$ rm master.zip
[isabell@moondust cypht]$ composer install
[isabell@moondust cypht]$ cp .env.example .env

Configuration¶

The following options are already present in the .env file. You can modify them as described below so that you can log in to Cypht via IMAP using your Uberspace mail account credentials. If you prefer to use different settings, you can find a list of all available options in the config generator.

AUTH_TYPE=IMAP
IMAP_AUTH_NAME=Uberspace
IMAP_AUTH_SERVER=moondust.uberspace.de
IMAP_AUTH_PORT=993
IMAP_AUTH_TLS=true
USER_SETTINGS_DIR=/var/www/virtual/isabell/cypht-data/users
ATTACHMENT_DIR=/var/www/virtual/isabell/cypht-data/attachments
ENABLE_REDIS=false
ENABLE_MEMCACHED=false

Installation (Part 2)¶

Run the config generator script and create the directories that you have already specified in the configuration file. Then change the symlink to the document root to the newly created directory cypht/site/.

[isabell@moondust ~]$ cd /var/www/virtual/$USER/cypht/
[isabell@moondust cypht]$ php ./scripts/config_gen.php
[isabell@moondust cypht]$ cd ..
[isabell@moondust isabell]$ mkdir -p cypht-data/{attachments,users}
[isabell@moondust isabell]$ rm -r html
[isabell@moondust isabell]$ ln -s cypht/site html

Finish Installation¶

You're all set! Now, you can access https://isabell.uber.space in your browser to sign in.

Warning

Whenever you change settings in the web interface, you must navigate to the Save page (under the Settings menu item) and confirm the changes by entering your password. Alternatively, you can follow the prompt when logging out. If you do neither, your changes will be lost when your session expires. This is currently the intended behavior, but may change in future versions.

Tuning¶

Cypht supports Redis and Memcached to improve performance, which we initially disabled in the configuration above. You could now configure them correctly and use them. The official config generator provides further explanations of the options available in the .env file.

Activate 2FA¶

It's a good idea to add an extra layer of security with 2FA (two-factor authentication). To do this, as with some other features, you'll first need to enable a module. You can find an overview of all the included modules on the official website. Modules are activated via the CYPHT_MODULES entry in the .env file. Add the value 2fa to this entry:

CYPHT_MODULES="core,contacts,local_contacts,ldap_contacts,gmail_contacts,feeds,jmap,imap,smtp,account,idle_timer,desktop_notifications,calendar,themes,nux,developer,profiles,imap_folders,sievefilters,tags,history,2fa"

You'll also need to add a secret to the APP_2FA_SECRET entry. To generate one, you can use the following command:

[isabell@moondust ~]$ LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 64; echo
hbCt1GeNfSGD9RxJjnRFi7jZNzQza8dcmvDxy5zqMshF7S6XaOLwvL9pKUOpyEb

Now run the config generator script again:

[isabell@moondust ~]$ cd /var/www/virtual/$USER/cypht/
[isabell@moondust cypht]$ php ./scripts/config_gen.php

Log in to Cypht, navigate to Site (under the Settings menu item), and select 2 Factor Authentication. Scan the QR code with an authenticator app, enter the generated code, and click on Verify code, then Save. If you don't have an app yet, take a look at 2FAS or Ente Auth.

Updates¶

Note

Check the update feed regularly.

Back up the following files and directories:

.env (contains all your environment-specific settings)
/var/www/virtual/isabell/cypht-data/users (contains user settings)
/var/www/virtual/isabell/cypht-data/attachments (contains all uploaded email attachments, but it is not critical if your emails are still on the server)

Download and unzip the new version as described above, but into a temporary directory. Insert the files and directories you just backed up. Now run the config_gen.php script again and make sure that the document root points to the correct directory, as described in Installation (Part 2).