Installing z-push on Debian 9

z-push is a great tool. It pretends to be an Exchange server, allowing you to have your IMAP server push emails to phones and other clients as if the client was talking to a real Exchange server.

In this tutorial we will use an apache2 vhost with a LetsEncrypt cert, install z-push from source. The version of z-push we will be using is 2.4.5 and php version 7.0. All commands are assumed to be running as root. You can also install z-push from their Debian repos, which I will go through in another blog post

Creating folder structure

First we need to create a folder structure for our apache vhost. In this example, I will use the /domains/z-push.example.com as the base folder. To facilitate upgrading at a later date, we will use symlinks from the specific version and state to the apache vhost config

cd /domains/z-push.example.com

mkdir -p logs public_html-2.4.5 state-2.4.5

ln -s /domains/z-push.example.com/public_html-2.4.5 /domains/z-push.example.com/public_html

ln -s /domains/z-push.example.com/state-2.4.5 /domains/z-push.example.com/state

chown -Rh www-data:www-data /domains/z-push.example.com/*

Installing z-push

There are a few ways you can install z-push. Here I will install from source and not use the z-push repos.

cd /domains/z-push.example.com/

git clone https://stash.z-hub.io/scm/zp/z-push.git source # Clone the repo

cd source

git checkout tags/2.4.5 # Git checkout the correct version

cd src

mv * /domains/z-push.example.com/public_html # Move these files to the correct location for the vhost

cd /domains/z-push.example.com

rm -rf source # Source is no longer needed

Configuring z-push

In this example we will use an IMAP backend. There are two config files that you need to worry about – /domains/z-push.example.com/public_html/config.php and /domains/z-push.example.com/public_html/backend/imap/config.php

The former is the main config file, and the latter is the IMAP specific config we will use. Find these values and update them

vim /domains/z-push.example.com/public_html/config.php

You need to set the following options from their defaults. WordPress makes a complete and utter mess of the single quote symbol, so these changes are in this gist

define(‘TIMEZONE’, ‘Europe/Dublin’);


define(‘STATE_DIR’, ‘/domains/z-push.example.com/state/’);


define(‘LOGFILEDIR’, ‘/domains/z-push.example.com/logs/’);


define(‘BACKEND_PROVIDER’, ‘BackendIMAP’);

Now we can work on the IMAP configuration. We will assume the IMAP server is imap.example.com and supports SSL connections. Again, because of the mangling I’ve uploaded a gist of the below here

vim /domains/z-push.example.com/public_html/config.php

You need to set the following options from their defaults:

define(‘IMAP_SERVER’, ‘imap.example.com’);

define(‘IMAP_PORT’, 993);

define(‘IMAP_OPTIONS’, ‘/ssl/norsh’);

define(‘IMAP_FOLDER_CONFIGURED’, true)

That’s it, the basic config is done. You may need to edit a few more things in this file in order to get the correct folder structure

Installing dependencies

We will need to install a few dependencies – note, in the standard Debian repos we are limited to PHP 7.0. There are repos available that offer a more up to date version of PHP such as, at the time of writing, PHP 7.3. We’re assuming we’re using the standard Debian repos

apt install -y php php-cli php-imap php-mbstring libapache2-mod-php7.0

Apache config

I’m assuming you have already setup apache with a vhost and a LetsEncrypt cert. There are lots of guides out there if you need help doing this. Below is my vhost file for z-push.example.com. The config is available as a gist here

After the vhost has been configured, you need to bounce the apache process.

service apache2 restart

Conclusion

You should now be able to add in your email address as an exchange account on your device. Set the server to be z-push.example.com and your standard IMAP username and password