Requirements
------------

Cypht requires at least PHP 5.6, with the OpenSSL and cURL extensions. You will
also need PDO support if using any database features. Testing is done on
Debian and Ubuntu platforms with Nginx, Apache, standard PHP, and HHVM. We also
use Composer to manage our few PHP dependencies.

On Debian based systems you can bring in the dependencies this way;
$ sudo apt install php php-fpm php-mbstring php-curl composer

1. 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
hm3.ini 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

# grab latest code
wget https://github.com/cypht-org/cypht/archive/master.zip

# unpack the archive
unzip master.zip

# run composer if it's there
if [ -x /usr/bin/composer ]; then
    cd cypht-master && composer install && cd ..
else
    echo "You may need to install php's composer."
fi

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

# copy to destination folder
sudo mv cypht-master/* $DESTINATION

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


2. Configure the program
------------------------

To configure Cypht for your environment, you must first edit the .env.dist file
to your liking, then run the config_gen.php script to generate config/dynamic.php
configuration file and assets used at run-time.

First edit the .env.dist file to configure Cypht for your environment. If you
choose to use a database for any of the 3 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 config/app.php
file, DB Sessions section. All configs files have lots of comments explaining what 
each option does.

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 config/app.php). You can put these directories anywhere, just make sure the
values in the config file point to the right place.


3. Generate the run-time configuration
--------------------------------------

Cypht now utilizes dotenv and configuration files in the config/ directory, 
such as *.php files. To update the run-time configuration, follow these steps:

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

This command will dynamically generate config/dynamic.php configuration file based on the settings in your updated configuration files. With the transition to dynamic configuration dotenv, there's no need to run the config_gen.php script anymore. The configuration updates automatically based on changes in config/*.php files.


4. 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.


5. 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:


# 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


6. 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.


7. Other INI files
------------------
Each Cypht module now has its own dedicated configuration file, conveniently located at the same directory of configs files and under `config/services.php`. These configiration files eliminate the need for scattered ini files and offer a more organized approach to managing module settings.

To configure a module, navigate to the respective file in the `config/` directory or `config/services.php` and customize the settings according to your requirements. Whether it's a module-specific file or the unified `services.php`, any changes made here will seamlessly integrate into the main configuration without the necessity of manually running the `config_gen.php` script.

Github
Cypht can connect to github and aggregate notification data about repository
activity.

Example github.ini file:
https://github.com/cypht-org/cypht/blob/master/config/services.php

Authorize an application for github:
https://github.com/settings/developers

OAUTH2 over IMAP
Gmail and Outlook.com support OAUTH2 authentication over IMAP. This is
preferable to normal IMAP authentication because Cypht never has access to your
account password.

Example oauth2 ini file:
https://github.com/cypht-org/cypht/blob/master/config/services.php

Authorize an application for gmail
https://console.developers.google.com/project

Authorize an application for outlook.com
https://account.live.com/developers/applications/

LDAP contacts
Cypht can use an LDAP server for contacts.

Example ldap.ini file:
https://github.com/cypht-org/cypht/blob/master/config/ldap.php

WordPress
Cypht can aggregate WordPress.com notifications.

Example wordpress.ini file:
https://github.com/cypht-org/cypht/blob/master/config/services.php

Authorize an application for WordPress.com:
https://developer.wordpress.com/apps/

Custom themes
You can create your own themes for Cypht. Edit the themes.ini file to include
your theme, and put the css file in modules/themes/assets.

https://github.com/cypht-org/cypht/blob/master/config/themes.php

Having problems?

I'm happy to help trouble-shoot any installation issues you run into. Send a
message to jason@cypht.org and I will get back to you as soon as I
can.
