Install Cypht v2.x

You can install specific versions of Cypht:

Cypht v2.x

Cypht has four differents installation ways:

Please read the bellow explanations about each way and pick one of your choice.

1. Manual installation

Requirements

Cypht 2.x requires at least PHP 8.1,Composer 2, and at minimum the OpenSSL, mbstring and cURL extensions. Cypht can also leverage several other extensions as defined in composer.json. Testing is done on Debian and Ubuntu platforms with Nginx and Apache.

Before proceeding please make sure your system meets minimal requirements

Steps

1. Check minimum requirements

#!/bin/bash

# You need to check php version which should be >=8.1
php --version

# Next you need to check composer version which should be >=2.0.0
composer --version

# List installed PHP extensions. at least OpenSSL, mbstring and cURL should be in the list
php -m

2. Download and prepare the code

It's important to consider where you put the Cypht source. The web-server will need read-only access to it, and moving it from one place to another requires re-running the configuration script. Do NOT put the source in the document root as this could create a security risk. On Debian, it's common to use the /usr/local/share/ sub-directory for a situation like this. Here is short bash script that will download the latest code, setup the correct permissions and ownership, put the source in /usr/local/share/cypht, and create a default .env file. It requires sudo access: 

#!/bin/bash

# this is where Cypht will be installed
DESTINATION="/usr/local/share/cypht"

# validate the destination directory
sudo test -r $DESTINATION -a -x $DESTINATION
if [ $? -ne 0 ]; then
    sudo mkdir $DESTINATION
fi

# create working directory
mkdir cypht-temp
cd cypht-temp

# Fetch latest release information
$latest_release = Invoke-RestMethod -Uri "https://api.github.com/repos/cypht-org/cypht/releases/latest"

# Extract tag name of the latest release
$latest_tag = $latest_release.tag_name

# Construct download URL for the latest release within the 2.x series
$download_url = "https://github.com/cypht-org/cypht/archive/refs/tags/$latest_tag.zip"

# Download the latest release
Invoke-WebRequest -Uri $download_url -OutFile "latest_cypht_release.zip"

# unpack the archive
unzip latest_cypht_release.zip

# run composer
cd latest_cypht_release && composer install && cd ..

# create a .env file
cp latest_cypht_release/.env.example latest_cypht_release/.env

# fix permissions and ownership
find latest_cypht_release -type d -print | xargs chmod 755
find latest_cypht_release -type f -print | xargs chmod 644
sudo chown -R root:root latest_cypht_release

# copy to destination folder
sudo mv latest_cypht_release/* $DESTINATION

# remove working directory
cd ..
sudo rm -rf cypht-temp

3. Configure the program

To configure Cypht for your environment, make adjustments to the .env file according to your preferences. The .env file serves as the primary configuration file.

First edit the .env file to configure Cypht for your environment. If you choose to leverage a database for authentication, sessions, or user settings, ensure to complete the relevant sections within the .env file based on the information provided in the config/app.php file.

The necessary SQL commands for creating tables can be found in the config/app.php file, specifically starting from line 617 in the "DB Sessions" section.

Cypht needs read, and read-write access to a few directories on the server. For security reasons these should NOT be inside the web-server document root. A good place for these is under the /var/lib/ sub-directory. Here are the commands To create the required directories per the default values in the ini file (assuming your web-server software runs as the "www-data" user).

          sudo mkdir /var/lib/hm3
          sudo mkdir /var/lib/hm3/attachments
          sudo mkdir /var/lib/hm3/users
          sudo mkdir /var/lib/hm3/app_data

          sudo chown -R www-data /var/lib/hm3/

The /var/lib/hm3/users directory is only required if you are using the file-system and not a database to store user settings (user_config_type = file in the .env). You can put these directories anywhere, just make sure the values in the ini file point to the right place.

4. Generate Dynamic Run-Time Configuration

Cypht utilizes a build process to create an optimized configuration and to combine and minimize page assets. Previously, after editing the hm3.ini file, the configuration and asset minimization were generated using the following steps:

cd /usr/local/share/cypht  (or wherever you put the code in section 1)
sudo php ./scripts/config_gen.php

Recent updates have streamlined the process, and running the command above will now specifically generate the config/dynamic.php file. This file incorporates dynamic configurations, including 'handler_modules,' 'output_modules,' and 'input_filters.' Furthermore, the command continues to optimize the configuration and combine/minimize page assets, ensuring efficient runtime operation.

Additionally, executing this command will create a sub-directory called 'site' that contains the code and page assets required within the document root. If you ever relocate the source location, you'll need to re-run the config_gen script to update the program.

5. Enable the program in your web-server

The easiest way to serve Cypht is to symlink it to the web-server document root. You can also copy the generated files to your web-server location, but then you will need to re-copy them anytime the config_gen script is run. If the source is located at /usr/local/share/cypht, and the web-server document root is at /var/www/html, the following command will make Cypht available under the "mail" path of the web-server:

sudo ln -s /usr/local/share/cypht/site /var/www/html/mail

Now going to https://your-server/mail/ should load the Cypht login page. Note that If you use a symlink, your web-server must be configured to follow symlinks.

6. Users

Setting up users depends on what type of authentication you configure in the config/app.php file. If you are using the local database configuration for users, there are scripts in the scripts/ directory to help manage them: 

# Generate necessary tables to manage users,sessions, or settings depending on the configuration in the .env file
php ./scripts/setup_database.php

# create an account
php ./scripts/create_account.php username password

# delete an account
php ./scripts/delete_account.php username

# change an account password
php ./scripts/update_password.php username password

7. Debug mode

Cypht has a debug or developer mode that can be used to troubleshoot problems or enable faster development of modules. To enable the debug version of Cypht, just sym-link the entire source directory instead of the site sub-directory:

sudo ln -s /usr/local/share/cypht /var/www/html/mail-debug

Debug mode is not as efficient as the normal version, and it is NOT designed to be secure. DO NOT RUN DEBUG MODE IN PRODUCTION. You have been warned! Debug mode outputs lots of information to the PHP error log that can be useful for trouble-shooting problems. The location of the error log varies based on your php.ini settings and web-server software.

8. Other Configs files

Some Cypht modules necessitate additional configuration files for proper setup. It is crucial that these files are NOT located within the web-server document root. Certain modules may require configuration with a service provider, particularly those related to Oauth2 client setup (such as Github, WordPress, Oauth2 over IMAP for Gmail, and Outlook). After configuring related files, there is no need to rerun the config_gen script; the changes will be automatically merged into the main configuration settings.Alternatively, you can clear your app cache.

2. Install cypht using Docker

Using Docker is one of the easiest way to install cypht as the cypht docker image comes with all the steps required in the manual instalation done for you. But the bad news is that this installation way requires docker knowledge.
Here is the cypht docker repository: https://hub.docker.com/r/cypht/cypht
To run containers required by cypht, please, first make sure you have docker and docker-compose installed on your system, then take a look on the section "example docker-compose" of repository overview, then do the following:

NOTE: Please change usernames and passwords before using the given docker-compose code in your production environment.

3. Install Cypht on a YunoHost server

This is an other easy way of installing and use Cypht.
YunoHost is an operating system that aims to simplify server administration as much as possible to democratize self-hosting while remaining reliable, secure, ethical and lightweight. It is a free software project owned exclusively by volunteers. Technically, it can be seen as a distribution based on Debian GNU/Linux and can be installed on many types of hardware.
To learn more about YunoHost, visit https://yunohost.org/en/overview/what_is_yunohost

To install Cypht on YunoHost, please follow these steps:

4. Install Cypht within Tiki

If you have tiki installed, you can use Cypht within tiki. This is an easy way of installing Cypht.
Please follow the following link for a complete guide of how to install and use cypht within Tiki.
https://doc.tiki.org/Webmail


Having problems?

We are happy to help trouble-shoot any installation issues you run into. Chat with us at Gitter Cypht at Gitter and We'll get back to you as soon as we can.

Page on Github
Edit here

Fill out an issue at Github
Submit an issue

Chat with us at Gitter
Cypht at Gitter

Want to contribute?
Cypht website contribution