How to Setup WISE Local Development

Hiroki Terashima edited this page Oct 17, 2018 · 14 revisions

Table of Contents


This is a quick and easy way to start developing WISE using java, maven, and git on Mac and Windows PC. It uses maven's embedded-tomcat server and hsqldb and configures WISE to default settings. If you have problems, please ask us on our Gitter channel, create an issue, or email the developer list:!forum/wise-dev

What You Need

  • A Mac or Windows PC running Windows 10 with admin permission
  • JDK 8
  • Maven 3.3+
  • Git 1.7+
  • Node & NPM (NPM comes installed with Node) We've tested on Node v6.9.5

For mac users, it may be easiest to use brew to install the dependencies.

$ brew install maven
$ brew install node
$ brew install git

Initial Set Up

  1. Download and install jdk, maven, git, and node. Set JAVA_HOME variable to point to your jdk, and add maven to your PATH.

Mac OSX:

  (change below as needed and add in ~/.bash_profile)
  export JAVA_HOME=`/usr/libexec/java_home -v 1.8`
  export PATH="/usr/local/maven-3.3.9/bin":$PATH

  (read the new settings)
  $ source ~/.bash_profile

Enable Developer Mode

When installing Git, make sure that you also install the Git Bash tool

Add new JAVA_HOME variable and point to your jdk:

Add path_to_maven_install\bin to your path:

Verify that you have the correct settings:

  1. Clone WISE project
 $ git clone
 Cloning into 'WISE'...
 remote: Reusing existing pack: 12456, done.
 remote: Counting objects: 165, done.
 remote: Compressing objects: 100% (112/112), done.
 remote: Total 12621 (delta 64), reused 151 (delta 50)
 Receiving objects: 100% (12621/12621), 158.19 MiB | 2.56 MiB/s, done.
 Resolving deltas: 100% (4890/4890), done.
 Checking connectivity... done

2.1 Check out PortalRedesignAngular branch (Active working branch since January 2018)

 $ git checkout PortalRedesignAngular

2.2 Install node dependencies

 $ npm install
  1. Make script file executable
 $ cd WISE
 WISE $ chmod u+x
  1. Run with "dev" param. This will configure WISE to use default settings, create database tables and populates them with initial values, and start WISE using maven's embedded tomcat server. The first time will take a while, so go get some coffee while it runs!
 WISE $ ./ dev

 [INFO,CustomDispatcherServlet,localhost-startStop-1] FrameworkServlet 'dispatcher': initialization started
 [INFO,CustomDispatcherServlet,localhost-startStop-1] FrameworkServlet 'dispatcher': initialization completed in 1219 ms
 Jan 18, 2014 1:34:20 PM org.apache.coyote.AbstractProtocol start
 INFO: Starting ProtocolHandler ["http-bio-8080"]

When you see these lines at the end, WISE is running on localhost:8080.

  1. View WISE on your browser. Go to http://localhost:8080/wise/index.html.

    To get you started quickly, WISE comes with sample users:
  • sample admin user: admin/pass
  • sample teachers: preview/wise

You can also create your own accounts via the WISE create account page.
  1. That's it. You can go off on your own, or follow steps in "First time getting started" page if you want to learn how to add projects to your WISE instance:

  2. To stop WISE, issue an abort command to kill the tomcat process (ctrl-c).

Persist Data Across WISE Restarts

Next time you want to run WISE and use the same data (accounts, student logs, etc), run with the "dev" command

 WISE $ ./ dev

Reset Data to Initial State

To wipe-out any previously-saved data and start with a fresh sample user data (sample teachers, students, projects, runs, etc), run with the "reset" command.

 WISE $ ./ reset

Then, start WISE by running with the "dev" command.

 WISE $ ./ dev

Making and Testing Changes

You can make changes to WISE using your favorite text editor.

As you are developing, if you are only making changes in jsp, javascript, html, or css files (src/main/webapps/**/[.jsp,.es6,.js,.html,.scss,.css]), you don't need to restart. Your changes will be reflected in your browser immediately when you save the file and refresh the browser.

When you make changes to other files (*.java, *.properties), you will need to stop WISE by killing the tomcat process with "ctrl-c" and restarting it by running "./ dev".

Here's the WISE5 design documentation and notes:

To see more details about WISE5 theming and styling, visit

Coding Conventions


Committing Changes

Use command-line git or git client tools like GitHub Client/SourceTree/Tower to commit your changes back to the GitHub project.

Running Unit Tests

WISE uses karma for unit testing client applications and JUnit junit for testing server-side code. These tests are run every time a new change is committed to the codebase. You can see the current build result here.

Step 1. run the client-side unit tests

  WISE $ npm test

Step 2. run the server-side unit tests

  WISE $ mvn test

Running Integration Tests

WISE uses protractor for testing the front-end code. Currently these tests are run on the developer's machines, but in the future, we would like to set it up so that they would run every time a new change is committed to the codebase.

Step 1. Read the instructions on protractor site to install protractor. Try running the sample tests on the page to get familiar with how it works.

Step 2. Download the Self-Propelled Vehicles WISE5 Project from and save it in src/main/webapp/curriculum/demo project. When you are finished, your directory should look like this:

  WISE $ ls -la src/main/webapp/curriculum/demo/

Step 3. Make sure WISE is running:

  WISE $ ./ dev

Step 4. Open up a new terminal and start the webdriver-manager inside your WISE directory

  WISE $ webdriver-manager start --standalone

Step 5. Open up a new terminal and run the tests:

  WISE $ protractor src/main/webapp/wise5/test-e2e/conf.js

Using MySQL Instead of HSQLDB

To use MySQL5.7 instead of the default HSQLDB, follow these steps. Please note that we support only up to MySQL 5.7 at the moment (working on supporting MySQL 8 in the future).

  1. Download, install, and start MySQL if you don't have it already. If you're using a mac, use homebrew to install v5.7 (brew install mysql@5.7. If you have problems switching versions, try restarting your computer) if not, download and install via

  2. Stop WISE if it's running. To stop WISE, issue an abort command to kill the tomcat process (ctrl-c).

  3. Open src/main/resources/, uncomment the properties related to mysql, and comment the properties related to hsqldb so it looks like this:



  1. 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 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;
  1. Create tables for wise_database by reading in the src/main/resources/wise_db_init.sql file.
  # 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 < src/main/resources/wise_db_init.sql
  1. Start WISE.
 WISE $ ./ dev

Using a Different Port

You can manually change the port that will be used to run WISE. By default, WISE runs on port 8080. Let's say that you want to run WISE on port 9000 instead.

  1. Stop WISE (ctrl-c)

  2. In WISE/pom.xml, change the "port" element in "org.apache.tomcat.maven" plugin section:

  1. In WISE/src/main/resources/, change "wiseBaseURL", "curriculum_base_www", and "studentuploads_base_www":
  1. Start WISE
 WISE $ ./ dev


Please write to the developer mailing list if you get stuck!!forum/wise-dev

Trouble Logging in as Admin

If you see "no output folder" exception in the console when you log in as admin, you will need to run the script as root.

 WISE $ sudo ./ dev

See here for details about this exception:

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.