Install

Install Cypht

Cypht has four differents installation ways:

1. Manual installation

Requirements

Cypht 1.4.x requires PHP 5.6 to 7.4. For PHP 8.1+, please use Cypht 2.x+, 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 >=5.6 for version 1.4.x and 7.4 for Cypht version 2.x.x
        php --version
        # Next you need to check composer version which should be >=2.0.0
        composer --version

It's important to consider where you place 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 it could create a security risk. On Debian systems, it's common to place the source in the "/usr/local/share/" sub-directory for such cases. The provided bash script downloads(installs or upgrades) the specified version of Cypht, prepares the necessary directories, sets up correct permissions and ownership, and places the Cypht source in "/usr/local/share/cypht/cypht-version". It also ensures that the required configuration files are created, such as .env or hm3.ini (depending on the version). The script requires sudo access to perform these actions: 

#!/bin/bash

bold_green() {
  echo -e "\033[1m\033[32m✓ $1\033[0m"
}

bold_red() {
  echo -e "\033[1m\033[31m$1\033[0m"
}

bold_blue() {
  echo -e "\033[1m\033[34m$1\033[0m"
}

bold_yellow() {
  echo -e "\033[1m\033[33m$1\033[0m"
}

# Function to check prerequisites
check_prerequisites() {
    echo "Checking prerequisites..."

    # Check if PHP is installed
    if ! command -v php &>/dev/null; then
        bold_red "Error: PHP is not installed or not in the system PATH."
        bold_red "Please install PHP before proceeding."
        exit 1
    fi

    # Print the PHP version
    bold_green "PHP is installed."

    # List installed PHP extensions
    required_extensions=("openssl" "mbstring" "curl")
    missing_extensions=()

    for ext in "${required_extensions[@]}"; do
        if ! php -m | grep -iq "$ext"; then
            missing_extensions+=("$ext")
        fi
    done

    if [ ${#missing_extensions[@]} -gt 0 ]; then
        bold_red "Error: The following required PHP extensions are missing: ${missing_extensions[*]}"
        bold_red "Please install the missing extensions before proceeding."
        exit 1
    else
        bold_green "All required PHP extensions (OpenSSL, mbstring, cURL) are installed."
    fi

    # Check if Composer is installed
    if ! command -v composer &>/dev/null; then
        bold_red "Error: Composer is not installed or not in the system PATH."
        bold_red "Please install Composer before proceeding: https://getcomposer.org/download/"
        exit 1
    fi

    # Print the Composer version
    bold_green "Composer is installed.\n"

}

# Function to fetch the list of valid tags from the GitHub repository
fetch_tags() {
    echo "Fetching latest versions from GitHub..." >&2  # Print to stderr to avoid mixing with output
    curl -s https://api.github.com/repos/cypht-org/cypht/releases | \
    jq -r '.[] | select(.created_at > "2018-11-13T03:58:48Z") | .tag_name' | sort -V | \
    awk -F. '
    {
        major = substr($1, 2)  # Extract major version number (e.g., "1" from "v1.x.y")
        latest[major] = $0     # Always update the latest version for this major version
    }
    END {
        # Print the latest version for each major version
        for (major in latest) {
            print latest[major]
        }
    }' | sort -V  # Sort the final output by version
}

# Function to install Cypht for a given version
install_cypht() {
    local version=$1
    local destination="$BASE_DIR/cypht-$version"

    # Check if the destination directory already exists
    if [ -d "$destination" ]; then
        bold_yellow "Cypht version $version already exists at $destination."
        read -p "Do you want to overwrite it? (yes/no) [yes]: " overwrite
        overwrite="${overwrite:-yes}"  # Default to 'yes' if no input is provided
        if [[ "$overwrite" != "yes" ]]; then
            bold_red "Installation aborted."
            exit 0
        else
            bold_blue "Overwriting existing installation..."
            sudo rm -rf "$destination"
        fi
    fi

    # Create destination directory
    bold_blue "Creating directory for version $version: $destination\n\n"
    sudo mkdir -p "$destination"

    # Create temporary working directory
    temp_dir=$(mktemp -d)
    cd "$temp_dir" || exit 1

    # Download the selected version of Cypht
    if [ "$version" == "master" ]; then
        bold_blue "Downloading the latest development version (master branch)..."
        wget "https://github.com/cypht-org/cypht/archive/refs/heads/master.zip" -O "master.zip"
        archive_name="master.zip"
        extracted_folder="cypht-master"
    else
        bold_blue "Downloading version $version..."
        wget "https://github.com/cypht-org/cypht/archive/refs/tags/$version.zip" -O "$version.zip"
        archive_name="$version.zip"
        extracted_folder="cypht-${version#v}"
    fi

    if [ $? -ne 0 ]; then
        bold_red "Error downloading version $version."
        exit 1
    fi

    # Unpack the archive
    bold_blue "Unpacking the archive...\n"
    unzip "$archive_name"

    if [ $? -ne 0 ]; then
        bold_red "Error unpacking the archive."
        exit 1
    fi

    # Run composer
    cd "$extracted_folder" || exit 1
    bold_blue "Installing dependencies with composer...\n"
    composer install

    # Handle configuration file creation

    if [[ "$selected_version" =~ ^v1 ]]; then
        bold_blue "Creating hm3.ini from hm3.sample.ini\n"
        cp hm3.sample.ini hm3.ini
    else
        bold_blue "Creating .env from .env.example....\n"
        cp .env.example .env
    fi

    # Fix permissions and ownership
    bold_blue "Fixing permissions...\n"
    find . -type d -exec chmod 755 {} \;
    find . -type f -exec chmod 644 {} \;

    # Ask for group (root is default for other systems, or user for macOS)
    read -p "Enter the group to own the files [root]: " group
    group="${group:-root}"

    sudo chown -R root:"$group" .

    # Move files to the destination folder
    bold_blue "Copying files to $destination...\n"
    sudo mv ./* ./.[!.]* "$destination"

    # Clean up temporary directory
    cd ..
    sudo rm -rf "$temp_dir"

    if [ $? -ne 0 ]; then
        echo "Error moving files to $destination."
        exit 1
    fi
    bold_green "Cypht $version installed successfully to $destination"
}

# Main script execution

# Check prerequisites
check_prerequisites

# Fetch available version tags
available_versions=$(fetch_tags)
available_versions=$(echo -e "$available_versions\nmaster")  # Add master branch to the list

# Display available versions
echo "$available_versions" | nl -s '. '

# Prompt user to select a version
read -p "Enter the version number (e.g. 1 for $(echo "$available_versions" | head -n 1)) [master]: " version_choice
version_choice="${version_choice:-$(echo "$available_versions" | grep -n "master" | cut -d: -f1)}"

# Get the version based on the user’s choice
selected_version=$(echo "$available_versions" | sed -n "${version_choice}p")

if [ -z "$selected_version" ]; then
    bold_red "Error: Invalid version choice. Please select a valid number from the list."
    exit 1
fi

# Prompt user for BASE_DIR
read -p "Enter the base directory for Cypht installation [/usr/local/share/cypht]: " BASE_DIR
BASE_DIR="${BASE_DIR:-/usr/local/share/cypht}"

bold_blue "Installation of version: $selected_version"
install_cypht "$selected_version"

To configure Cypht for your environment, you must first edit the "hm3.ini" (for Cypht 1.4.x) or ".env" (for Cypht 2.x.x) file to your liking, .env content can be generated using the Cypht Config Generator, then run the "config_gen.php" script to generate the optimized configuration file and assets used at run-time.

For Cypht 1.4.x, begin by editing the "hm3.ini" file to configure Cypht for your environment. If you choose to use a database for any of the three available purposes (authentication, sessions, or user settings), you will need to complete the "DB support" section and create the required tables. SQL to do so can be found in the "hm3.sample.ini" file. The "hm3.ini" file contains many comments explaining each configuration option and how to set it up for your environment. 

        sudo mkdir -p /var/lib/hm3/{attachments,users,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 "hm3.ini" or ".env"). You can put these directories anywhere, just make sure the values in the ini file point to the right place.

4. Generate the run-time configuration

Cypht uses a build process to create an optimized configuration, and to combine and minimize page assets.Once you have edited your "hm3.ini" or ".env" file, generate the configuration with:

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

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 hm3.ini file. If you are using the local database configuration for users, there are scripts in the scripts/ directory to help manage them:

        # 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 INI files

Some Cypht modules require additional ini files to be configured. These should NOT be inside the web-server document root. Cypht will look for them in the location defined by "app_data_dir" in the hm3.ini file. A sample ini file for each module set that requires one is included in the source for that module. To configure them you must copy the sample ini file to the "app_data_dir" and edit it for your setup. Some of these require configuring your service with a provider, specifically ones related to Oauth2 client setup (Github, WordPress, Oauth2 over IMAP for Gmail and Outlook). Re-run the config_gen script after configuring an ini file and it will be merged into the main configuration settings.

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 requiresdocker knowledge.
Here is the cypht docker repository: https://hub.docker.com/r/sailfrog/cypht-docker
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/whatsyunohost

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.