Skip to content

Latest commit

 

History

History

sync

README.md

IMAP Sync

This application synchronises IMAP accounts to a local MySQL database. You can use this as a standalone method to periodically download your email. The script is meant to run forever with almost zero maintenance :D

Web Client Admin Interface

Sync Web Screenshot

Command Line Interface

Sync Screenshot

Contents

Dependencies

At a glance, this application requires the following:

  • PHP 7.0 or newer
  • MySQL / MariaDB 10.0 or newer
  • ext-pdo, ext-iconv, and ext-mbstring

It's recommented to install ext-mysqlnd as well. php7.0-common should already be installed on your system.

Versions 7.1 and 7.2 are confirmed working, and this codebase is actively developed in version 7.2. See below for info about PHP 5.6.

1. Support for PHP 5.6

Version 1.0.0 of this application supports PHP 5.6, with compatibility for all of the composer dependencies at that snapshot.

If you'd like to use that, run the following command:

$> git checkout 1.0.0

All current and future updates will only support PHP 7.0 and higher!

Installation

1. Create Database

To get started, make sure you have MariaDB or MySQL running and issue the following command:

MariaDB [(none)]> CREATE DATABASE `libremail`;

The database name is a configuration option, so if you'd like to change this to be something other than libremail, make sure you update the config setting.

1.1 max_allowed_packet (MariaDB/MySQL)

Because of the amount of data that may be written to SQL (long email message text) a configuration setting needs to be enabled for MySQL databases allowing a larger packet size to be sent in a query. To do this, add the following line to your SQL config file:

[mysqld]
max_allowed_packet = 512M

You don't have to use 512MB as your packet size, but anything 16MB or higher is advised.

1.2 Configuring max_allowed_packet for non-SUPER SQL databases (Amazon RDS)

If your SQL user account does not have SUPER privileges, you will have to set the max_allowed_packet config setting manually. In Amazon RDS, these parameters can be changed by creating a "customized parameter group" in the RDS admin panel.

2. Configure the Application

Configuration options are saved in config/default.ini. Do not modify this file or anything in it. All of your changes should go into config/local.ini and should be in the INI file format, just like the default file. If you would like to make changes to config/local.ini but not ever commit them, run the following:

$> git update-index --assume-unchanged config/local.ini

View all possible configuration options: Configuration Options

3. Install Composer Dependencies

Download the vendor packages via Composer:

$> composer install

This will create a vendor directory with all of the project's PHP dependencies.

4. Running the Diagnostic Tests

You can run a test to see if the application is installed correctly, and that all dependencies and pre-requisites are met. To do that, run:

$> ./sync --diagnostics

You can also use -d as a short flag. This will go through and check the database connection, that all paths are writeable, and some other tests and see if the sync script will run correctly. These tests are run in the background before any sync happens, but you can access them this way for more detailed information in the case that something is failing.

5. Running SQL Migration Scripts

Before you can start syncing, run the SQL database scripts:

$> ./sync --updatedb

You can also use -u as a short flag. This will create all the SQL tables and run any other database operations.

Run the Sync

If you'd like, you can run ./sync --help to see a list of what options you have. View all possible configuration options and their details: Configuration Options

To use the CLI tool (debug mode), run:

$> ./sync

and follow the onscreen instructions.

To use the Web tool, run:

$> ./libremail

This tool will run silently and write to /logs. Open your browser and go to localhost:9898 to view the Web client.

Using an Init Script or Supervisor

If you'd like to run this sync script in the background all the time, then it is recommended to use some sort of supervisor or watchdog program to monitor if the script fails for any reason. Here are some guides for Linux and MacOS:

Submitting Bugs

All bugs and requests are tracked in the Github Issues for this repository. See the Issues Page for a listing of the open and closed tickets. Please search the closed issues before reporting anything to see if it has been resolved :)

This is an open source project that is worked on in spare time, so there is no guarantee that anything that you report will be looked at or fixed! However I will make a personal effort to resolve everything in a timely manner, and odds are good that I'll check it out quickly as I'm personally using this project to manage my own email.

Software Licenses

The Sync application includes the following 3rd party packages:

  1. JavaScript
    1. Reconnecting WebSocket, Joe Walnes
    2. Mustache.js, Jan Lehnardt
  2. CSS
    1. Skeleton CSS Boilerplate, Dave Gamache
    2. Normalize CSS, Nicolas Gallagher
  3. PHP
    1. PDO, Mike Gioia, ParticleBits
    2. IMAP, Mike Gioia, ParticleBits
    3. Laminas Mail, Laminas Project, forked maintained by Mike Gioia, ParticleBits
    4. Laminas Mime), Laminas Project, forked maintained by Mike Gioia, ParticleBits
    5. Laminas Service Manager), Laminas Project
    6. Pimple, Fabien Potencier, Symfony
    7. Monolog, Jordi Boggiano
    8. CLImate, Joe Tannenbaum, PHP League
    9. Particle Validator, Jordi Boggiano
    10. Belt, Ilya S.
    11. Force UTF-8, Sebastián Grignoli
    12. ReactPHP EventLoop, Igor Wiedler and Chris Boden, ReactPHP
    13. ReactPHP ChildProcess, Igor Wiedler and Chris Boden, ReactPHP
    14. ReactPHP PCNTL bindings, Marius Krämer
    15. Événement, Igor Wiedler
    16. Symfony Event Dispatcher, Fabien Potencier, Symfony