#!/bin/cat 
# $Id: INSTALL.OnlineUI.txt,v 1.32 2019/11/28 14:42:17 gilles Exp gilles $

This documentation is also located online at 
https://imapsync.lamiral.info/INSTALL.d/
https://imapsync.lamiral.info/INSTALL.d/INSTALL.OnlineUI.txt

=======================================================================
               Installing imapsync online
=======================================================================

Please consider this as relatively experimental.
However, to a certain extent, I'm now confident with /X 
since the /X service is up and running quite well since January 2017.

=======================================================================
                    Hardware consideration

RAM used per imapsync process, mean value: 230 MB.
Average_bandwidth_rate: 345 KiB/s ~ 2.8 Mbps.
Load mean: 0.8 on a CPU 4 cores "Intel(R) i5-2320 3.00GHz K8-class"




=======================================================================
                    Installation
                    
You have to be a little familiar with what a CGI script is
and how to activate a CGI script on the Apache 
HTTP server, or any other HTTP server. Linux is also a 
preferred platform (I run /X service on Linux and FreeBSD).

I have tested yet this visual interface on Mac. It works
but for now it demands some skills few Mac users have.

I have tested this visual interface on Windows,
it fails on Windows because of some hard coded Unix paths.
I'm working on it to be Windows ok but it's not done yet (october 2019).

Some users have successfully installed a /X visual interface 
on Windows using a Linux VM machine.

The web visual user interface frontend /X is compounded in four
files: a html5 file, a css file, a javascript file and
a logo image:

* https://i005.lamiral.info/X/imapsync_form_extra.html
* https://i005.lamiral.info/X/imapsync_form.css
* https://i005.lamiral.info/X/imapsync_form.js
* https://i005.lamiral.info/X/logo_imapsync_Xn.png


You can do a "view source" to see the html file as 
it is written, and a "save" to get it locally.
The three other files can be saved the same way or
with wget.

Those four files can be put anywhere on a web server,
as long as they stand in the same directory. If you
want to put them in different directories, just change
the content of imapsync_form_extra.html to reflect the change,
ie, change the two lines referencing imapsync_form.css and imapsync_form.js 
  href="imapsync_form.css" (near the beginning of imapsync_form_extra.html)
  src="imapsync_form.js"   (near the end of imapsync_form_extra.html)
I let you changing the image logo as an exercise, it's safe if you fail.

The actual imap syncing work is done by imapsync acting as a CGI,
the visual interface is only there to give imapsync the parameters
needed for the sync.

Use at least Perl module CGI.pm release 4.08 (2014-10-18)
to avoid the bug "Undefined subroutine CGI::multi_param".
You can use the command cpanm to upgrade CGI.pm to its last version,
it's the easiest way.

Print the CGI.pm release with:

  perl -MCGI -e 'print "$CGI::VERSION\n"'

If it is under release 4.08 (2014-10-18) then upgrade it with

  cpanm CGI

It is a good thing to remove the old one if it was installed
by a distribution package, I let you this part as an exercise too.

To check and fix the Perl modules dependencies, run:

  cd
  wget -N https://imapsync.lamiral.info/prerequisites_imapsync
  sh prerequisites_imapsync

In order to make imapsync work as a cgi, there is two conditions.
First, imapsync has to work by itself on the web host.

If imapsync doesn't work by itself, as a command line, 
then it won't work as a cgi.

Second, imapsync has to work by itself on the web host using
the Unix user running the web server. Detailed examples to 
verify that will be provided further in this document.

The imapsync_form_extra.html file in action calls the CGI location
/cgi-bin/imapsync
which has to be imapsync itself, the file script (not the directory).

The very latest and relatively stable imapsync is at
https://imapsync.lamiral.info/imapsync
This file is the program file used verbatim for the service given at
https://i005.lamiral.info/X/

Copy the three files imapsync_form.* on a directory that is exported 
by your HTTP server.
Copy the imapsync script on the cgi-bin/ directory
allowing CGIs and you'll have your own imapsync visual interface
and service. The cgi-bin/ directory is usually outside the 
hierarchy exported to anybody by the HTTP server.

Now that I have explained the general context for any system,
I'll describe concrete examples on several systems, 
Debian/Ubuntu and Centos. Feedbacks show that the Centos
process is easier in case you know just a little of the
linux distributions.

=============================================================================
A) Concrete example on a Debian server with Apache:

Imapsync script place on the server disk:
/usr/lib/cgi-bin/imapsync

Get and install latest imapsync:

  cd
  wget -N -O /usr/lib/cgi-bin/imapsync  https://imapsync.lamiral.info/imapsync
  chmod +x /usr/lib/cgi-bin/imapsync

 Check it like this:

  cd
  /usr/lib/cgi-bin/imapsync --testslive

Assuming that the Unix account running Apache is www-data, 
check that it will work under Apache with this command:

  su -s /bin/sh -c 'SERVER_SOFTWARE=foo /usr/lib/cgi-bin/imapsync' www-data

  wget -nv -S -O-  http://localhost/cgi-bin/imapsync?testslive=1

It should print something like:
Status: 200 OK to sync IMAP boxes. Load on bar is ...
...


This classical /cgi-bin directory is already configured 
in the Apache configuration file
/etc/apache2/sites-available/default-ssl
or
/etc/apache2/sites-available/default

The configuration file contains the following section
somewhere, maybe in comments for now, ie, with 
some # characters 
at the beginning to make them ignored:

ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
<Directory "/usr/lib/cgi-bin">
    AllowOverride None
    # Next line "no-gzip 1" is to avoid output buffering, 
    # clients can then see the log along the sync
    SetEnv no-gzip 1
    Options +ExecCGI -MultiViews
    Order allow,deny
    Allow from all
</Directory>

The UI front-end file place on the server disk in
this example is
/var/www/html/X/imapsync_form_extra.html
but it can be placed it anywhere on disk, the important
thing is that it has to be served by the web server. 

  mkdir /var/www/html/X/
  cd /var/www/html/X/
  wget -N \
  https://i005.lamiral.info/X/imapsync_form_extra.html \
  https://i005.lamiral.info/X/imapsync_form.css \
  https://i005.lamiral.info/X/imapsync_form.js \
  https://i005.lamiral.info/X/logo_imapsync_Xn.png
  ln -s imapsync_form_extra.html index.html

The imapsync process working directory in cgi mode is
/var/tmp/imapsync_cgi/
it is not configurable unless changing it in
imapsync directly, it is hard-coded in imapsync. 
In this directory will go the log files and
the pid files.

Check 
   http://yourhost/X/imapsync_form_extra.html
or the safer
  https://yourhost/X/imapsync_form_extra.html

That's all for installing a /X service on Debian.

=============================================================================
B) Concrete example on a Centos 7 server with httpd Apache:

  mkdir /var/www/html/X/
  cd /var/www/html/X/
  wget -N \
  https://i005.lamiral.info/X/imapsync_form_extra.html \
  https://i005.lamiral.info/X/imapsync_form.css \
  https://i005.lamiral.info/X/imapsync_form.js \
  https://i005.lamiral.info/X/logo_imapsync_Xn.png
  ln -s imapsync_form_extra.html index.html
  
  cd
  wget -N https://imapsync.lamiral.info/imapsync
  chmod +x imapsync
  # some basic tests
  ./imapsync 
  ./imapsync --testslive

  cp imapsync /var/www/cgi-bin/
  su -s /bin/sh -c 'SERVER_SOFTWARE=foo /var/www/cgi-bin/imapsync' apache
  wget -nv -S -O-  http://localhost/cgi-bin/imapsync?testslive=1


Check 
   http://yourhost/X/imapsync_form_extra.html
or the safer
  https://yourhost/X/imapsync_form_extra.html

That's all for installing a /X service on Centos 7.

=======================================================================
=======================================================================


====== mod_perl failure ======

This part is for mod_perl experts only.
The script imapsync doesn't work under Modperl::Registry
nor under ModPerl::PerlRun. So read on if you think you
are better than me. 

I've try the standard way, telling how any cgi perl script
can be run under mod_perl perlrun, but it fails with imapsync.
Any hint welcome!

# This is a Debian example

# install mod-perl with

  apt-get install libapache2-mod-perl2

# edit the file /etc/apache2/mods-available/perl.conf
# with the following lines
  more /etc/apache2/mods-available/perl.conf

<IfModule mod_perl.c>
  PerlModule ModPerl::PerlRun
  Alias /perl-run/ /usr/lib/cgi-bin/
  <Location /perl-run>
      SetHandler perl-script
      PerlResponseHandler ModPerl::PerlRun
      PerlOptions +ParseHeaders
      Options +ExecCGI
  </Location>
</IfModule>

# Enable the Apache perl module

  a2enmod perl

# Verify perl.conf and perl.load are in directory mods-enabled/

  ls mods-enabled/perl.*

# Reload Apache

  apachectl graceful

# Verify imapsync works under perl-run

  curl http://localhost/perl-run/imapsync


=======================================================================
=======================================================================
