Instructions on getting the VMT development system on your computer, configuring it, and then using it to build and deploy a working VMT Server:

Note: If you have never setup and used the VMT Development System before setting it up and making it work may take a whole 8-hour day. Take your time and follow the instructions below carefully. The VMT Development System is made up of many technologies, each of which is changing over time and are sometimes different under different operating systems, so PLEASE add issues and workarounds you come across to this page! Thank you very much for your participation and patience. VMT Lead Developer, Dr. Baba Kofi Weusijana.

Deployment and Starting the Webserver:

1. Use Maven 2 to create and deploy the VMT .war files and start the Tomcat 6 web container (web server) using the following commands from the top-level VMT directory (you may have to proceed these with “sudo” and/or type your administrative account password if your don’t have write access to the webserver). a. If you need to stop the webserver:

mvn cargo:stop

b. To delete the webapps(during the “clean” phase), rebuild the webapps, and deploy configurations to the webserver:

mvn -e clean package install

c. To deploy the webapps’ .war files to the webserver:

mvn -e cargo:deploy

d. If you need to now start the webserver:

mvn -e cargo:start

If you see an error like this:

java.lang.VerifyError: (class: de/fhg/ipsi/concertchat/server/ServerChannelModule, method: messageReceived signature: (Lde/fraunhofer/ipsi/agilo/common/message/IMessage;)V) Incompatible argument to function

don’t worry because its probably this known bug: http://www.coderanch.com/t/90811/JBoss/java-lang-VerifyError-Incompatible-object Just use this command before you start the webserver to avoid the error being thrown:

export CATALINA_OPTS="-noverify"

You will see in the log/console the error:

### Could not start the persistence manager module - no persistency/recovery available

We are currently ignoring this error as it currently occurs on the production server with no ill effects.

If you want run tomcat without using Maven, change to the tomcat6/bin directory and run one of the scripts there. If you want to debug the server run

sh debug.sh

in that directory. Further instructions for debugging a webserver with an IDE like Eclipse are at: http://mathforum.org/pow08/index.php/JPuzzler/GettingStartedDeveloping#Setting_up_Tomcat_in_debug_mode

The VMTLobby Webapp:

You can redeploy the VMTLobby webapp using the Tomcat manager: open your browser, go to http://localhost:8080/manager/html (or whatever tomcat URL you are using), undeploy the old version and upload (use the "WAR file to deploy" section) the new VMTLobby.war. If that fails, check that there is a user such as “vmt” with role “manager” in the aperson table. There can only be one active realm for tomcat and the one we are using defines roles for the application and for the manager page as well. You can add this user using the VMTLobby website. Use the handle ‘vmt’ and change the password to something like ‘Vmttest01’. Then you must change the role to manager by using the following SQL command:

update `aperson` set `Role`='manager' where `PersonID`=3

when the PersonID? was set to 3 by the database. When you are done the data row in the aperson table should look something like this:

| PersonID | Handle   | Password  | …| Role    | CommunityName | TypeID | 
|        4 | vmt      | Vmttest01 | …| manager | all           | [NULL] |

The ConcertChat Server for VMT Webapps:

The main VMT module for its ConcertChat server is cchat4vmt which produces the vmtChat.war. The cchat4vmt module has several sub-modules: concertchat (Concert Chat source from SourceForge?), vmt-ccext-stubs (client Web Service stubs that is also used by VMTLobby), vmtChat, and vmtClient. There is also a cc2vmt module that produces a cc2vmt.war that was used for testing purposes but might be no longer relevant.

Using VMT:

Leave the terminal window open and open a browser window. Type in the relevant manager URL which is probably: http://localhost:8080/manager/html Enter the manager tomcat-user account username and password and check to see if all the webapps started and are running fine. Then try logging-into the VMT Lobby, the URL probably is: http://localhost:8080/VMTLobby/ Use one of the default accounts to login. If the local information for the databases and the local tomcat directory was correct in the settings.xml, then you should see some content after login. Try creating a room and using it. Try logging-into the lobby in another Web browser as another user and then joining and using the same VMT room.

Sharing your work with the VMT Development Team:

Using the Math Forum Subversion Repository for VMT

Instructions for setting up Subversion and using it with Eclipse are in the GettingVMTDevSystem?.doc file you should have been given. If you don’t have it, please email Dr. Baba Kofi Weusijana at baba@mathforum.org and request the file. Currently to connect to our SVN repository you must be on-campus or using Drexel’s VPN. Eclipse uses its "Team" source version control tools for SVN. Here are two places to get documentation on it: Full documentation: http://www.eclipse.org/subversive/documentation/teamSupport.php Simple tutorial: http://www.ibm.com/developerworks/opensource/library/os-ecl-subversion Basically you should right-click on what project, folder, or file you are interested in and use an option under "Team". Updating means to get the latest version from the repository. Synchronizing means comparing your file(s) to the repository (you can also use the "Compare With" right-click menu options). If a conflict is found (you have changed a file that someone else also changed) its might be best to contact the developer who made the change to come to an agreement on what the new merged file’s contents should be. Committing means submitting your file(s) to the repository as the latest version. Do not commit changes you have not tested! Also please provide a comment each time you commit some changes so that it is easy to understand why you made your changes and go back to that revision if needed. Please do not commit the Maven “target” folders as they contain files built by Maven. The best way to avoid that is to run
mvn –e clean
to remove all “target” folders before you synchronize and commit. SVN is primarily for storing source code, adding built artifacts unnecessarily increases the size of the repository and built artifacts often only work on the platform and language encoding under which they were built. The same is true for the “bin” folder Eclipse sometimes makes at the root folder of a project; please don’t commit them to the SVN repository. You can tell SVN to ignore an item by right-clicking on it and choosing Team->Add to svn:ignore… (you might have to choose Team->revert… first). Built JARs belong in the JAR repository (see below). Please update this instruction file if you notice a mistake or an omission!

Using the Math Forum Archiva JAR Repository for VMT

Whenever you are done making changes to VMT and commit them to the SVN repository, you should also update the JAR repository with your new VMT JARs. Currently to connect to our Archiva JAR repository you must be on-campus or using Drexel’s VPN. First type:

mvn –e clean package install

which will build and test your version of VMT and install its JAR files into your local Maven repository. Then type:

mvn –e deploy

That command will upload via the Web (HTTP protocol) your version of the VMT JARs to the Math Forum Archiva JAR repository. Do NOT use the

mvn deploy:deploy

command as it currently doesn’t work for VMT. Due to a bug in Apache’s Archiva (http://jira.codehaus.org/browse/MRM-770) do NOT use the classifier tag for any component you are using or developing.

You can deploy just one jar using the

mvn deploy:deploy-file

command or just use this web page: http://zinc.mathforum.org:8080/archiva/upload.action. More information is available at: http://maven.apache.org/plugins/maven-deploy-plugin/usage.html.

If Maven ran out of memory (Java heap space) you can increase it by typing:

Under Windows:

set MAVEN_OPTS=-Xmx256m

Under UNIX systems:

export MAVEN_OPTS='-Xmx256m'

If you only want to use your local JAR repository so you don’t have to wait for JARs to download or be checked against the Archiva and default Maven repositories, you can run Maven in offline mode by using the –o option like this:

mvn –o clean package install

It helps to cleanup your local JAR repository every now and then. There is no way as of yet to force Maven to re-download poms it has already [see bug MNG-1258]. Poms are being updated without version number increment even though they shouldn't. If the problem might exist with VMT artifacts only, removing [local-maven-repository]/org/mathforum/vmt should be enough. Remember that the Maven repository usually is located in the folder:

[Windows]

C:\Documents and Settings\<Your Login Name>\.m2\repository

[Unix]

~/.m2/repository

VMTwiki WebApp?:

Installing PHP5:

Macs: You can’t use the default PHP5 with Tomcat6 because it lacks php-cgi (and I can’t find a way to add it). Download and install this special build for Macs from: http://www.entropy.ch/software/macosx/php

Other Operating Systems: See the appropriate page for your OS on the MediaWiki? installation page and it will explain how to install PHP5: http://www.mediawiki.org/wiki/Manual:Installation_guide copy and rename php.ini-dist to php.ini

Integrating PHP5 with Tomcat6

Get the latest stable version of Java Bridge with its documentation (should be a file with a name like php-java-bridge_5.4.4.2_documentation.zip) from: http://sourceforge.net/projects/php-java-bridge/files/ Extract the file and use the cd terminal command to go inside of the resulting folder. Test your PHP installation with:

java -classpath JavaBridge.war TestInstallation

If the test results are fine, follow the instructions on this page under the section “Configure Tomcat for PHP”: http://php-java-bridge.sourceforge.net/pjb/tomcat6.php If the test doesn’t work, just use the more common Apache webserver to serve VMTwiki. Apache is usually already installed for Mac OS 10.5. If you need to install it, first read about how from the installation instructions for your operating system linked from: http://www.mediawiki.org/wiki/Manual:Installation_guide

Installing MediaWiki?:

Follow the installation instructions for your OS linked from: http://www.mediawiki.org/wiki/Manual:Installation_guide

If when you try the MySQL? command:

mysql -u root -p -e "SET PASSWORD FOR wikiuser = OLD_PASSWORD(YOUR-WIKIDB-PASSWORD)"

you get the error:

ERROR 1133 (42000) at line 1: Can't find any matching row in the user table

Don’t worry about it because the Web-based installation process will set it for you.

After you move the mediawiki-1.x.x folder to your web server, name the folder “vmtwiki”.

For the wiki configuration page:

Follow the instructions to install: Fill in the details it asks for and wait while the installer does its work. The system will ask for the following information:

Site configuration:

   1. Wiki name. Fill in “VMT”
   2. Contact email. Fill in your email address
   3. Language. Choose from drop down list
   4. Copyright/license. Select from: no license metadata (VMT Wiki’s default), GNU Free Documentation License 1.2, A Creative Commons license.
   5. Admin username and password. Fill in with the administrative username and password you use to log into the VMTLobby
   6. Whether caching will be turned on. Off is what we generally use for VMT. If caching is turned on, you must specify the memcached servers you are using.

Email configuration:

Enable all of these after testing that your sendmail program is working. Otherwise, disable them all.

   1. Whether email features are enabled globally.
   2. Whether user-to-user email is enabled.
   3. Email notification. Select from disabled, enabled for changes to user discussion pages only, or preferably, enabled for changes to user discussion page and to pages on watchlists.

          If email is enabled, whether email address authentication is enabled.

Database configuration:

   1. Database type. Select from MySQL? or PostgreSQL?.
   2. Database host name. Fill in.
   3. Database name. Use the default "wikidb".
   4. Database username. Use the default "wikiuser".
   5. Database password. Fill in the same password you used or tried when you made the wikidb database in earlier steps.
   6. Whether to use the superuser account to create the database user and tables. Check the box.
   7. Database superuser name. Fill in. Defaults to "root".
   8. Database superuser password. Fill in.

MySQL? specific options

         1. Database table prefix. If more than one wiki is to use the same database instance, the prefix will separate the wiki instances. Fill in.
         2. Database character set. Select “MySQL? 4.1/5.0 UTF-8”.

Once you have the wiki working with the new database, stop the wiki’s webserver, then move the vmtwiki folder outside the web server and replace it with the extracted contents of the vmtwiki.war file from http://vmt.mathforum.org/source/vmtwiki.war . Extraction can be done from a command line like this

jar xvf vmtwiki.war

although it can also be accomplished with some ZIP utilities. If the extracted folder is not named exactly “vmtwiki” then rename it so. Then edit the LocalSettings?.php to match your setup (especially your database connection setup). The best way to do that is use a text tool like BBedit to compare the LocalSettings?.php files. You must also configure the vmtwiki/LocalPerInstallation?.php file. You can use the LocalSettings?-example.php and LocalPerInstallation?-example.php files in the SVN repository as guides.

VMTDeployment-Revised

ConcertChat Server for VMT Webapps