Installation

From Tera-WURFL

You do not have permission to edit this page, for the following reasons:

• The action you have requested is limited to users in the group: Users.
• This page has been locked to prevent editing.

You can view and copy the source of this page:

__FORCETOC__ ==Installation== * Copy the files into a directory on your webserver that can be accessed from the internet. For the purposes of explaination I will refer to this location as <nowiki>http://yourserver.com/Tera-Wurfl/</nowiki>", with a local directory of "/var/www/Tera-Wurfl/". * Open a web browser and go to: <nowiki>"http://yourserver.com/Tera-Wurfl/admin/install.php"</nowiki> you should see the '''Tera-WURFL Installation''' page with a bunch of errors on it. The next steps will show you how to correct these errors. You can refresh this page to verify that your changes have taken effect. ===[[Configuration_File|Configuration File]]=== * Copy the file '''TeraWurflConfig.php.example''' to [http://www.tera-wurfl.com/Tera-Wurfl_Doc/TeraWurfl/TeraWurflConfig.html TeraWurflConfig.php], then edit it. Each setting is described in comments and on the [[Configuration File]] page. The only thing you NEED to modify is the database info (user, pass, db, etc)<br>NOTE: By default, Tera-WURFL is configured to use MySQL 5.x. If you are using a different database, set the [[DatabaseConnector|DatabaseConnector]] accordingly. ===File Permissions=== * By default, the DATADIR is set to "data/". This directory holds the wurfl.xml file, your patch file(s) and the log file. This directory and EVERYTHING in it needs to be accessible (read+write) by the user that runs your webserver. This is normally "apache", "www-data" or "nobody" in Linux. <pre>chown -R apache:apache ./data/</pre> * Verify that the permissions errors on the installation page are fixed by refreshing the browser. ===Database Configuration=== Tera-WURFL supports MySQL (default), MSSQL 2005+ and MongoDB. Since MongoDB does not require any specific configuration, the following instructions apply to MySQL and can be easily translated to MSSQL. * Create a new database for Tera-WURFL and a user that has a minimum of the following privileges on the new database:<br> **SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, CREATE TMP TABLE, **CREATE ROUTINE, ALTER ROUTINE, EXECUTE * In the config file, set the DB_HOST, DB_USER, DB_PASS and DB_SCHEMA. * Verify that the database errors on the installation page are fixed by refreshing the browser. If the database tables don't exist yet they will be created for you when you load the WURFL file. See the [[Configuration File]] page for more detailed information. ===Loading the Tera-WURFL Database=== * If you are satisfied with the results on the installation page, you can load the database with the WURFL data. There are three sources that the data can come from: *# Your local WURFL file: This will load the DATADIR/wurfl.xml file into your database. *# The current released WURFL: This will download the current wurfl.xml file from the official WURFL website and load it into your database. *# The current CVS WURFL: This will download the current unreleased CVS wurfl.xml file from the official WURFL website and load it into your database. * There will be a delay while the server loads/[[Downloads|downloads]] the WURFL, then you should see something like this: <pre> Database Update OK Total Time: 10.211848974228 Parse Time: 0.43991899490356 Validate Time: 2.7456870079041 Sort Time: 1.3005568981171 Patch Time: 0.44084501266479 Database Time: 3.9245390892029 Cache Rebuild Time: 1.3603019714355 Number of Queries: 294 PHP Memory Usage: 213.19 MB -------------------------------- WURFL Version: www.wurflpro.com - 2009-08-25 08:15:48 (Tue Aug 25 08:19:41 -0500 2009) WURFL Devices: 13714 PATCH New Devices: 3036 PATCH Merged Devices: 2 Update Complete! </pre> If there are errors, they are most likely problems connecting to the WURFL site or permission problems trying to write the temporary downloaded file to the DATADIR directory. Also, many users have reported a "memory allocation" error - to fix this look for "OVERRIDE_MEMORY_LIMIT" in the config file. If there are no errors, click on "Return to administration tool". ===[[Web Administration Page]]=== * Verify that the WURFL is loaded by clicking on "Statistics, Settings, Log File". You should see that there is data in your MERGE and INDEX tables. The CACHE table will fill up with cached data as devices access your site, and it will be cleared ONLY if you click on "Clear the device cache" from [[Web Administration Page|main administration page]]. * Click on "Tera-WURFL test script" to test the installation. You can type in any user agent to search for it in the WURFL. If you have caching enabled (default), the first time you search for a user agent you will see the total number of queries that Tera-WURFL performed to find a match (unless there was no match). If there was a match, the device will be cached and the next time you search for it you will see "Total Queries: 1 (Found in cache)". Tera-WURFL only needed to perform 1 query since the devices full capabilities were cached. If you go back to the admin page and look at the settings, you will see that the CACHE now has a couple rows in it. You can verify the device was cached properly by going to "Cache Browser" from the [[Main_Page|main page]] and clicking on your user agent. ===Security=== * You should delete the admin/install.php file if everything is working ok. * Protect your 'admin' directory by using a method specific to your web server software. For Apache, this means a [http://www.mobilefish.com/developer/apache/apache_quickguide_htaccess.html#protect .htaccess file] would work. ==Upgrading Tera-WURFL== ===Version 1.x to Version 2.x=== Tera-WURFL 2 is a complete code-rewrite and has a different database schema. In order to upgrade, you must rename the old Tera-WURFL folder and unzip the new version into the folder you would like to use. It is recommended that you use a new database as well, then delete the old one when you have Tera-WURFL 2 working properly. ===Version 2.x to Version 2.x=== To upgrade from any 2.x to any other 2.x (i.e. Tera-WURFL 2.0.0 to Tera-WURFL 2.1.0), simply delete the Tera-WURFL folder and unzip the new version's files into the folder you want to use. The databases are backwards compatible, so you can keep your existing data. After the files are in place, go to the [[Web Administration Page]] and update the database, then test it by going to the Tera-WURFL test page. ==Usage Example== Here is a very simple example: <geshi lang=php lines=0> <?php // Include the Tera-WURFL file require_once('./TeraWurfl.php'); // instantiate the Tera-WURFL object $wurflObj = new TeraWurfl(); // Get the capabilities of the current client. $matched = $wurflObj->getDeviceCapabilitiesFromAgent(); // see if this client is on a wireless device (or if they can't be identified) if(!$wurflObj->getDeviceCapability("is_wireless_device")){ echo "<h2>You should not be here</h2>"; } // see what this device's preferred markup language is echo "Markup: ".$wurflObj->getDeviceCapability("preferred_markup"); // see the display resolution $width = $wurflObj->getDeviceCapability("resolution_width"); $height = $wurflObj->getDeviceCapability("resolution_height"); echo "<br/>Resolution: $width x $height<br/>"; ?> </geshi> ==Available Capabilities== The complete list of capabilities is available at the [http://wurfl.sourceforge.net/help_doc.php#product_info WURFL Documentation Page] or via the [http://www.scientiamobile.com/wurflCapability/tree ScientiaMobile Capability Browser]. If you use <span class="inline-code">$wurflObj->getDeviceCapability("cap_name")</span> you can just use the capability name from the WURFL site, otherwise you can access it directly from the TeraWurfl object's capabilities array like this: <span class="inline-code">$wurflObj->capabilities['group_name']['cap_name']</span> You can also browse the capabilities of all the mobile devices in the WURFL using the [http://www.tera-wurfl.com/explore/ Tera-WURFL Explorer] ==Troubleshooting== Be sure to head over to the [http://www.tera-wurfl.com/forum/ Tera-WURFL Forums] to post your questions if there are not answered here! ===Submit User Agent for Analysis=== If you have gone through the relevant troubleshooting steps below and you're still having trouble with a particular device, you can submit it to us for analysis online at [http://www.tera-wurfl.com/ua_submission/ http://www.tera-wurfl.com/ua_submission/]. Alternately, if you're using Tera-WURFL 2.1.1 or newer, you can submit your user agents directly from the [[Web Administration Page]]. ===PHP Problems=== ====Fatal error: Allowed memory size of...==== When you try to update the database from the [[Web_Administration_Page|Web Administration Page]], you see the following: <pre>Fatal error: Allowed memory size of 67108864 bytes exhausted (tried to allocate 24 bytes) in TeraWurflLoader.php on line 287</pre> This is an indication that PHP on your server does not have access to enough memory (RAM) to process the WURFL file. It takes a large amount of memory to process the wurfl.xml file because the entire file needs to be parsed, sorted, checked for consistency, then loaded into the database. To remedy this problem, edit your [http://www.tera-wurfl.com/Tera-Wurfl_Doc/__filesource/fsource_Tera-WURFL__TeraWurflConfig.php.html TeraWurflConfig.php] file. Make sure <span class="inline-code">$OVERRIDE_MEMORY_LIMIT = true</span> and <span class="inline-code">$MEMORY_LIMIT = "768M"</span>. On many shared hosts, you will only be allowed to use a small amount of memory per process (typically 64M), which is too small for Tera-WURFL to parse the WURFL file and build the database tables. Here are two typical workarounds: # Install Tera-WURFL at another location, like your development system, and update it from there, then copy its database up to the production environment # Use the [[WURFL_Customizer|WURFL Customizer]] to remove unused capabilities from the WURFL file, then upload this smaller file to your server and use it to update Tera-WURFL. ===Database Problems=== ====Error in DB RIS Query: Thread stack overrun==== <pre>Fatal error: Uncaught exception 'Exception' with message 'Error in DB RIS Query: Thread stack overrun: 5224 bytes used of a 131072 byte stack, and 128000 bytes needed. Use 'mysqld -O thread_stack=#' to specify a bigger stack.. Query: CALL TeraWurfl_RIS('SonyEricssonK700i/R2AC SEMC-Browser/4.0.2 Profile/MIDP-2.0 Configuration/CLDC-1.1',16,'SonyEricsson') ' in /var/www/html/Tera-Wurfl/DatabaseConnectors/TeraWurflDatabase_MySQL5.php:103 Stack trace: #0 /var/www/html/Tera-Wurfl/UserAgentMatchers/UserAgentMatcher.php(63): TeraWurflDatabase_MySQL5->getDeviceFromUA_RIS('SonyEricssonK70...', 16, Object(SonyEricssonUserAgentMatcher)) #1 /var/www/html/Tera-Wurfl/UserAgentMatchers/SonyEricssonUserAgentMatcher.php(30): UserAgentMatcher->risMatch('SonyEricssonK70...', 16) #2 /var/www/html/Tera-Wurfl/TeraWurfl.php(96): SonyEricssonUserAgentMatcher->applyConclusiveMatch('SonyEricssonK70.. in /var/www/html/Tera-Wurfl/DatabaseConnectors/TeraWurflDatabase_MySQL5.phpon line 103</pre> To fix this problem, edit your MySQL [[Configuration_File|configuration file]] and increase the size of the thread stack. ====Error in DB RIS Query: PROCEDURE TeraWurfl_RIS does not exist==== <pre>Fatal error: Uncaught exception 'Exception' with message 'Error in DB RIS Query: PROCEDURE TeraWurfl_RIS does not exist. Query: CALL TeraWurfl_RIS('SonyEricssonK700i/R2AC SEMC-Browser/4.0.2 Profile/MIDP-2.0 Configuration/CLDC-1.1',16,'SonyEricsson') ' in /var/www/html//Tera-Wurfl/DatabaseConnectors/TeraWurflDatabase_MySQL5.php:103 Stack trace: #0 /var/www/html/Tera-Wurfl/UserAgentMatchers/UserAgentMatcher.php(63): TeraWurflDatabase_MySQL5->getDeviceFromUA_RIS('SonyEricssonK70...', 16, Object(SonyEricssonUserAgentMatcher)) #1 /var/www/html/Tera-Wurfl/UserAgentMatchers/SonyEricssonUserAgentMatcher.php(30): UserAgentMatcher->risMatch('SonyEricssonK70...', 16) #2 /var/www/html/Tera-Wurfl/TeraWurfl.php(96): SonyEricssonUserAgentMatcher->applyConclusiveMatch('SonyEricssonK70...') #3 /var/www/html/Tera-Wurfl/TeraWurfl.php(202) in /var/www/html/Tera-Wurfl/DatabaseConnectors/TeraWurflDatabase_MySQL5.phpon line 103</pre> This error indicates that the TeraWurfl_RIS procedure did not get properly created in the MySQL Database. This procedure is dropped and created every time the database is loaded. There are only three reasons for you to get this message: * You have never updated your database from the [[Web_Administration_Page|Web Administration Page]] * Your database user (specified in [http://www.tera-wurfl.com/Tera-Wurfl_Doc/__filesource/fsource_Tera-WURFL__TeraWurflConfig.php.html TeraWurflConfig.php]) does not have the [[#Database Configuration|required permissions]] in MySQL * Your TABLE_PREFIX in TeraWurflConfig.php is empty. This prevents the creation of the stored procedure. ====Other MySQL Problems==== * If you are using MySQL 4, you '''must''' set the Database Connector in [http://www.tera-wurfl.com/Tera-Wurfl_Doc/__filesource/fsource_Tera-WURFL__TeraWurflConfig.php.html TeraWurflConfig.php] to MySQL4, NOT the default, MySQL5. * There are some cases where using a replicated backend MySQL server will result in the Stored Procedures not being propagated to all the servers in the replication group. In this case, Tera-WURFL cannot use the Stored Procedures and must be configured to run without them.<br> '''To use a MySQL5 Server ''without using Stored Procedures'', use the MySQL4 Database Connector in the [[Configuration_File|configuration file]].''' ===Detection Problems=== ====Device Detected Incorrectly==== Sometimes Tera-WURFL will incorrectly detect your device. This is most often caused by the RIS Algorithm (Reduction in String).<br> Here's an example User Agent string from Windows XP, Internet Explorer 6: <pre>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322; .NET CLR 2.0.50727; .NET CLR 3.0.04506.30; .NET CLR 3.0.04506.648; .NET CLR 3.5.21022; .NET CLR 3.0.4506.2152; .NET CLR 3.5.30729)</pre> The User Agent is reduced by removing one character at a time from the end of the string. In this case, it would eventually be reduced to this: <pre>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;</pre> Each time the string is reduced, the database is checked for a macthing User Agent in the respective [[Main Page#How Does it Work|UserAgentMatcher]] table. Often times there are many matching User Agents, and Tera-WURFL will have to arbitrarily choose one of the matching User Agents from the table. Typically, Tera-WURFL will choose the first User Agent in the list that is an ''actual device'' as opposed to a ''categorial device'' (i.e. iPhone_3G_ver1 instead of Apple_Webkit.)<br> In order to accurately detect this device, one of the following must happen: * If it's a ''new'' wireless device, it must be added to the WURFL project via http://www.wurflpro.com or the Yahoo WML Mailing List * If it's a ''new'' desktop web browser, the user agent can be added to the web_browsers.xml file at http://wurfl.sourceforge.net by emailing the Yahoo WML Mailing List * If it's an ''existing'' desktop web browser, you can add it to the Tera-WURFL Custom Patch File via the [[Web_Administration_Page|Web Administration Page]]. To do this, just go to your admin page and click on '''Generate Patch File''', then paste the User Agent into the list and click the '''Generate Patch File''' button and go back to the main admin page and click '''Update WURFL from local file'''. This will override the entries in the WURFL file and detect the device properly. ===Performance Problems=== ====Updating the WURFL is slow==== A typical server will be able to update the database from the WURFL and apply any patches in about '''20 seconds'''. After the WURFL file is processed, the cache is rebuilt be redetecting each User Agent in the TeraWurflCache database table one-by-one. A typical server will redetect the cached entries at a rate of about '''100 per second'''. To see how many devices are in your cache file, go to your [[Web_Administration_Page|Web Administration Page]], then click on [[Settings Page|Settings, Statistics, Log File]]. Look for the '''CACHE''' entry on left side of this page and you will see the number of rows (devices) in the cache. If you divide this number by 100 you will get an estimated time to rebuild the cache; add 20 seconds to it to get the estimated time it will take to update the WURFL file ''and'' rebuild the cache. '''NOTE''': it may take longer to update if you are using a slower than average server, or if you are using the MySQL4 or MSSQL Database Connector.<br> As an example, a cache with 20000 devices in it will take about 220 seconds, or 3 minutes, 40 seconds.

Return to Installation.