Upgrading TCAT

Every now and then TCAT receives important upgrades or bugfixes. It is recommended to keep your installation up-to-date. Please follow these steps when upgrading your own installation.

Short version

disable controller.php in your crontab
kill all dmitcat processes (i.e. controller.php, dmitcat_*)
remove all files in the proc directory
pull the latest code
optionally run common/upgrade.php (see the upgrade section below)
re-enable controller.php in your crontab

Long version

Remove controller.php from your system crontab

On your command line, type crontab -e to edit the crontab. Make sure you edit the crontab as the user for which you made dmi-tcat/logs, dmi-tcat/proc and dmi-tcat/analysis/cache writeable.

Prepend your crontab line with the comment symbol (#) during the upgrade. E.g.: # * * * * * (cd /var/www/dmi-tcat/capture/stream/; php controller.php)

Make sure to save your changes.

Kill all running dmitcat processes

You need to make sure TCAT is not running. Either reboot your server, or kill the processes manually. For manual killing, log in to your server or console, then find all the processes related to TCAT and kill them one-by-one. For example: Log into your console or server, then head to the installation directory of tcat and execute:

$ ps aux | grep php | egrep 'dmitcat|controller'
john      426  0.0  0.3 262188 14848 pts/5    S    16:09   0:00 /usr/bin/php /var/www/dmi-tcat/capture/stream/dmitcat_follow.php
john    32638  0.5  0.3 263568 15876 pts/5    S    16:08   0:07 /usr/bin/php /var/www/dmi-tcat/capture/stream/dmitcat_track.php
john    32655  0.7  0.2 263568 15876 pts/5    S    16:08   0:01 /usr/bin/php /var/www/dmi-tcat/capture/stream/controller.php
$ kill 426
$ kill 32638
$ kill 32655

( the number in the column after john specifies the process ID you will need to kill )

Completely remove all files in the proc/ directory

Log into your console or server, then head to the installation directory of tcat and execute:

$ rm -f proc/*

Do a git pull to get the latest version of the source code

Log into your console or server, then head to the installation directory of tcat and execute:

$ git pull

(OPTIONAL) Upgrade your database using the upgrade script

See

Re-enable controller.php in your system crontab

We are ready to bring TCAT back online. Remove the comment symbol (#) you've added in an earlier step so that controller.php will start again automatically.

Inspect the contents of controller.log

The root folder of your TCAT installation contains a folder called logs with all the logfiles. After a succesful upgrade, controller.log should look something like this:

2014-09-24 15:08:00 script track was not running - starting
2014-09-24 15:09:01 script track is running with pid [32638] and has been idle for 2 seconds
2014-09-24 15:10:04 script track is running with pid [32638] and has been idle for 12 seconds
2014-09-24 15:11:02 script track is running with pid [32638] and has been idle for 8 seconds
2014-09-24 15:12:09 script track is running with pid [32638] and has been idle for 18 seconds

If you get warning messages and TCAT is not capturing new tweets, please copy the error messages from controller.log and all recent messages from track.error.log, follow.error.log and/or onepercent.error.log when you file an issue here on Github.

Upgrading database tables

New releases of TCAT may involve significant changes in the database architecture. Generally, these apply only to new tables. We do not apply such changes automatically, because if you have huge data sets they might take a very long time to complete. Please read the release announcements for specifics.

Before you run the upgrade script, stop all tracking and controller processes and disable the controller.php in your crontab (as specified above).

The general procedure to keep your database architecture up-to-date is very simple. Log into your console or server, then head to the installation directory of TCAT and execute:

$ cd common/
$ php upgrade.php

WARNING This script will take a very long time to complete if you have a big dataset (and even days if you have a huge dataset). You might want to run it in a screen by issuing the command screen before running any other commands. This will make sure the process keeps running in the background when the connection to your server gets lost.

If you run php upgrade.php without arguments, all bins will be upgraded. You can also specify a single bin name as an argument; when invoked like that, it will restrict all upgrade operations to a single bin.

You should receive feedback about the upgrade process in your terminal and once the upgrade is finished, you can re-enable controller.php back in cron.

The upgrade.php script can be safely run multiple times. It will only consider bins and tables which need updates (and will thus not redo any completed operations).