How to Upgrade Time Tracker
This document describes how to upgrade Anuko Time Tracker from an older version to the latest. The upgrade procedure is relatively straightforward:
- Start with a working old version.
- Deploy a new code on the server and execute relevant update steps in dbinstall.php.
The rest of this page provides further details and describes some issues that may arise and how to solve them.
Before You Start
You'll need to have any one of the following
to start upgrading.
- Access to an older Time Tracker running.
- team_data.xml file. A team manager can create this file on the Export page in Time Tracker.
- Database dump.
We start with any one item from the above list, and, upon completion of the steps described below, have the latest Time Tracker running with migrated data.
Backup Database and Code
Backup your database and the code first in case something goes wrong and you need to rollback.
- Backup the database using mysqldump.
- Backup your existing code by making a copy of the directory from where Time Tracker runs.
Have Old Time Tracker Running
If you have the old version already running (your current production environment) make a copy of the code to another directory. Also, make a copy of the database and configure it to use it. This makes sure we don't interfere with production data during upgrade.
Alternatively, you can download and install the old version
of Time Tracker on another server. Issues may arise because your environment is now different. For example, a newer version of MySQL server may complain about timestamp syntax in mysql.sql:
`al_timestamp` timestamp(14) NOT NULL,
To make installation possible modify all such lines by removing the brackets with what is inside, so that it becomes:
`al_timestamp` timestamp NOT NULL,
Another common problem is PEAR configuration. Time Tracker starting from version 126.96.36.1993 uses PEAR that is built-into its own directory structure. Older versions need an externally installed PEAR with DB module. Integrated PEAR does not have DB module. Instead, it uses MDB2. Therefore, you may need to install PEAR separately.
If all goes well, by this point we have the older Time Tracker running, meaning that you can create a team on it and log time. Test it.
Start with Old Data
If you already have a working database copy, go to the next step. Otherwise, login to Time Tracker as admin (default password is "secret" without quotes) and import team from team_data.xml
file. A couple of issues may arise here if your file is large.
File Upload Error
If you see this, it means that the file cannot be uploaded, most likely because of its large size. One thing to try is to export a compressed
file from your original server to see if it works.
Another thing to try is to tweak the following values in php.ini to accommodate your file size:
Restart your web server for changes to take effect. Finally, in Time Tracker code, find and change the maxsize
value in this line in import.php
$form->addInput(array('type'=>'upload','name'=>'xmlfile','value'=>'browse','maxsize'=>16777216)); // 16 MB file upload limit.
// Note: for the above limit to work make sure to set upload_max_filesize and post_max_size in php.ini to at least 16M.
This should take care of the File upload error
Blank Page during Import after Timeout
If your data set is large, Time Tracker will timeout and display a blank page during the import operation. To fix this, adjust the following value in php.ini:
max_execution_time = 3600 ; Maximum execution time of each script, in seconds
your web server to notice the change.
If all goes well, you should see the Import completed successfully
message on screen when import is finished. Now we have old team data on the old version in Time Tracker.
Install New Time Tracker Code
- Remove old Time Tracker code.
- Download new Time Tracker code and deploy it.
- For UNIX systems set up full access rights for catalog ./WEB-INF/templates_c/ (chmod 777 templates_c).
- Prepare ./WEB-INF/config.php by first making it a copy of ./WEB-INF/config.php.dist and then adjusting the DSN string in it:
Upgrade Database Structure
Point your browser to dbinstall.php file in the root of Time Tracker installation. You should see something like this:
DB Install page in Time Tracker
Carefully execute update steps in sequence from top to bottom
that are relevant to the version you are upgrading from. For example, if you started from 0.9.7
, then all of the following steps must be done:
- Update database structure (v0.7 to v1.3.3)
- Update database structure (v1.3.3 to v1.3.40)
- Update database structure (v1.4.85 to v1.5.79)
- Update database structure (v1.5.79 to v1.5.97)
- Update clients
- Update custom fields
- Update tracking mode
Examine output at each step. It is normal to see some errors at the beginning of the first step as you may be upgrading from the middle of it and already have partially changed db structure. However, all of the following steps must produce no errors with the exception of step v1.4.85 - v1.5.79 (it may generate two errors when dropping non-existing indexes client_name_idx
, but no other errors).
If you clicked a wrong button and see a lot of errors, start over by having an original database, and then executing all steps in proper sequence. It may help if you prepare a check-list of the steps required and execute them one after another.
Dealing with Corrupted Characters after Upgrade
In some situations, an updated Time Tracker may show corrupted characters. There are at least 2 possible reasons for this.
If you use mysqldump, some characters may become double-encoded. The result of this is that characters like ß in "Straße" are displayed with two symbols
like "StraÃŸe" on your Time Tracker web pages. A solution to this issue is described here
Wrong Connection Charset
This character corruption manifests itself differently. Instead of double encoding you may see incorrect encoding for some characters. For example, accented French letters are displays as black diamonds with a question mark inside.
Corrupted French characters
It happens because database data are stored in one encoding (such as latin1
) but your connection string in DSN value in ./WEB-INF/config.php file uses a different charset or not uses one at all.
Note: prior to version 188.8.131.5298 the charset parameter was not provided
in ./WEB-INF/config.php.dist file. When charset is not specified, the default charset is used, whatever it is. Use the following mysql command to get some ideas of what the default charset might be on your system.
mysql> show variables where variable_name like 'character_set_%';
| Variable_name | Value |
| character_set_client | latin1 |
| character_set_connection | latin1 |
| character_set_database | latin1 |
| character_set_filesystem | binary |
| character_set_results | latin1 |
| character_set_server | latin1 |
| character_set_system | utf8 |
There are two ways to fix the charset issue.
For a quick fix specify the same charset in the DSN constant. For example, if your connection charset used to be latin1, use it after migration as well:
Or do not use one at all:
If it works - great! However, not using a connection charset, or using a wrong one (not utf8mb4) is a bad idea. It may get you into trouble during future upgrades. To fix this, try the following: convert the data to utf8mb4 with mysqldump, import the data into a new database, and then use utf8mb4
charset in the DSN constant in config.php. In other words:
- Dump the database using mysqldump.
- Restore it in to a new database.
- Use utf8mb4 charset in DSN string for database connections.
If all goes well, Time Tracker should be updated by now. If you need help with any of the above you can order a support incident
Time Tracker Install Guide