Skip to content

How to Set Up WISE on Your Server

Jump to bottom Edit New page
Hiroki Terashima edited this page Oct 3, 2018 · 2 revisions

Table of Contents

Introduction

This document will guide you through the process of setting up a server with your own WISE instance and updating it when a stable release becomes available. This model suits most people. If you want the latest and greatest WISE and/or would like to build WISE from source on the server, see this page: WISE Latest Deployment Model

If you encounter problems while setting up WISE, or would like to contribute to the open source effort, please email the WISE developer mailing list http://groups.google.com/group/wise-dev or chat with us on Gitter https://gitter.im/WISE-Community/WISE

Terminology

  • WISE consists of
    • "Portal": the user/course management system and
    • "Virtual Learning Environment (VLE)": the student view, teacher grading view, authoring view.
  • curriculum is the authored content, sometimes also referred to as "projects"

What you'll need

  • roughly 20-60 minutes
  • Java 1.8+
  • Apache Tomcat 8.5.x. Download Tomcat 8.5.x from here: http://tomcat.apache.org/. You can get the Binary, Core distribution as a zip or tar.gz
  • Set JAVA_HOME environment variable to the base path of the JDK.
  • Set CATALINA_HOME environment variable to the Tomcat install directory.
  • Mysql 5.5+
  • Server. We've had success with CentOS 5.2+,6.0+,7.0+, and Ubuntu 14.04 and 16.04. We strongly recommend using a linux server. You can also follow this page to install WISE on your local machine.
  • RAM:
    • running locally, for personal use: at least 1GB.
    • running on server with 1-30 concurrent users: at least 1 GB.
    • running on server with 30-250 concurrent users: at least 2GB.
    • running on server with 250+ concurrent users: at least 4GB.
    • running on server with 500+ concurrent users: at least 8GB.
  • Disk space:
    • running locally, for personal use: at least 2GB.
    • running on server with 1-1000 total users: at least 10 GB.
    • running on server with 1000-10,000 total users: at least 25GB.
    • running on server with 10,000+ total users: at least 50GB.
    • running on server with 100,000+ total users: at least 200GB.

Server layout

Path on server description
$CATALINA_HOME where you installed tomcat
$CATALINA_HOME/webapps tomcat's webapps directory, where wise.war will go
$CATALINA_HOME/webapps/wise.war you will be downloading wise.war here
$CATALINA_HOME/webapps/wise tomcat will put the exploded wise project here
$CATALINA_HOME/webapps/curriculum hosted directory for curriculum (authored-content) files
$CATALINA_HOME/webapps/studentuploads hosted directory for files uploaded by students
$CATALINA_HOME/logs/catalina.out tomcat log file

Installing WISE

1. Check that you have installed the items on "What you will need" section above.

2. Allocate more memory to Tomcat. Add the line below at the bottom of $CATALINA_HOME/bin/setclasspath.sh file. 

  JAVA_OPTS="$JAVA_OPTS -Xms1024m -Xmx2048m"

3. Create curriculum and studentuploads directory in $CATALINA_HOME/webapps. This is where curriculum files and files uploaded by students will go. 

  $ cd $CATALINA_HOME/webapps 
  $ mkdir curriculum studentuploads


Note: make sure to set appropriate ownership/permissions on 'studentuploads' and 'curriculum' directories so that your tomcat process can read/write. Most-likely you won't have to do anything if you are running the above commands as the same user that will start/stop the tomcat process. If you have trouble in the later steps, check the permissions/ownership of these folders!

4. Download wise-X.war from http://wise5.org and put it inside $CATALINA_HOME/webapps (X represents version). Make sure that the name is wise.war once it's downloaded. You should now have

  • $CATALINA_HOME/webapps/wise.war
  • $CATALINA_HOME/webapps/curriculum/ folder
  • $CATALINA_HOME/webapps/studentuploads/ folder
5. Set appropriate permissions and then start Tomcat (if needed). 
  $ cd $CATALINA_HOME/bin
  $ chmod u+x startup.sh
  $ chmod u+x setclasspath.sh
  $ chmod u+x catalina.sh
  $ ./startup.sh

Wait for tomcat to complete startup. This will explode the wise.war file from above and make this directory:

  • $CATALINA_HOME/webapps/wise/ and
Note: Here's a useful command to let you see the log output in real-time: 
  $ tail -f $CATALINA_HOME/logs/catalina.out

6. Set appropriate permissions and then stop Tomcat. 

  $ cd $CATALINA_HOME/bin
  $ chmod u+x shutdown.sh
  $ ./shutdown.sh

7. Copy $CATALINA_HOME/webapps/wise/WEB-INF/classes/wise_sample.properties to wise.properties. Then edit wise.properties as needed. 

  $ cd $CATALINA_HOME/webapps/wise/WEB-INF/classes/
  $ cp wise_sample.properties wise.properties
Modify $CATALINA_HOME/webapps/wise/WEB-INF/classes/wise.properties to match your settings. See comments within file for details.

Notes
  • Be sure to change curriculum_base_dir to point to the absolute path to your $CATALINA_HOME/webapps/curriculum directory.
  • If you're running on a public server and want the public to be able to see your instance of WISE, be sure to change "localhost:8080" with your appropriate hostname, like "wise.xyz.edu:8080".
  • If you want to specify your own database username/password/schema name, be sure to specify them in this file and note them for later step.
  • Be sure to change wiseBaseDir to point to the absolute path to your $CATALINA_HOME/webapps/wise directory.

8. Create new user and databases in MySQL. For this example, we'll create a new mysql user username/password=wiseuser/wisepass. The database will be called "wise_database". If you specified your own database username/password/schema name in the wise.properties file in the above step, remember to replace them accordingly. 
   # log in as root
   $ mysql -u root -p     
   # create new user wiseuser, password wisepass
   mysql> create user 'wiseuser'@'localhost' identified by 'wisepass';
   # create wise_database
   mysql> create database wise_database default character set=utf8;
   # give wiseuser access to the new database
   mysql> grant all privileges on wise_database.* to 'wiseuser'@'localhost';
   mysql> flush privileges;  
   mysql> exit;

9. Create tables for wise_database by reading in the $CATALINA_HOME/webapps/wise/WEB-INF/classes/wise_db_init.sql file. 

  $ cd $CATALINA_HOME/webapps/wise/WEB-INF/classes/
  # replace db name and db_username as needed below to create tables for wise_database
  # and load it with initial values.
  $ mysql wise_database -u wiseuser -p < wise_db_init.sql

10. Start Tomcat. This time, WISE will read in the new settings and connect to mysql. 

  $ cd $CATALINA_HOME/bin
  $ ./startup.sh

11. WISE can now be accessed via the browser. Go to http://your_ip_address_here:8080/wise/index.html

12. Log in and change your admin password. Also try adding a sample project to your WISE instance. Follow "First Time Getting Started" section on this page: https://github.com/WISE-Community/WISE/wiki/WISE-Administrator-Resources

13. Join the WISE developer mailing list at http://groups.google.com/group/wise-dev or come chat with us at https://gitter.im/WISE-Community/WISE. Tell us about how you'll be using WISE, your success stories, and places where you had trouble.

Updating WISE

1. Read the release notes to understand what has changed and what you will need to do specifically to upgrade to the new version: https://github.com/WISE-Community/WISE/releases

2. Make necessary backups. You want to make sure to backup the following:

  • data in database
  • curriculum folder
  • wise.properties file that you modified in section above.
  • any changes you've made to your instance of WISE that you want to carry over to the new version.
### example of saving database and the files to a backup folder
# make a backup directory on your home directory
  $ mkdir ~/backup      
  $ mysqldump --databases wise_database -u wiseuser -p > ~/backup/wise_db_backup_2010_09_05.sql
  $ cp $CATALINA_HOME/webapps/wise/WEB-INF/classes/wise.properties ~/backup/

3. Stop tomcat, by running $CATALINA_HOME/bin/shutdown.sh

4. Remove wise.war, and wise directory 

  $ cd $CATALINA_HOME/webapps
  $ rm -rf wise.war wise

5. Download the wise.war file from this page: http://wise5.org and put it inside $CATALINA_HOME/webapps. Make sure that the name is wise.war (no version number).

6. Start tomcat, by running $CATALINA_HOME/bin/startup.sh. This will explode the war file and make the right directories.

7. Stop tomcat, re-insert the files you backed up above into the right places. 

### example of re-inserting files from backup folder
  $ cp ~/backup/wise.properties $CATALINA_HOME/webapps/wise/WEB-INF/classes/wise.properties
8. Start tomcat.

9. Updated WISE can now be accessed via the browser. Go to http://your_ip_address_here:8080/wise/index.html

Troubleshooting

1. Problem importing a project

Problem: When I log in as admin and try to import a new project, I get a error message page "We're sorry, but the server has encountered an error. The staff has been informed about this problem."

Solution: This is likely a permission problem- WISE does not have permissions to access curriculum_base_dir that you specified in wise.properties file. Change the permission of curriculum_base_dir and student_uploads_dir appropriately. For example, you can change the permission to 755 (chmod 755 /path/to/curriculum_base_dir) and set the owner to tomcat8 (chown tomcat8 /path/to/curriculum_base_dir)

Useful Resources

  • Tomcat deployment guide http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html
  • Mysqldump reference http://dev.mysql.com/doc/refman/5.1/en/mysqldump.html
Add a custom footer
Add a custom sidebar
Clone this wiki locally