Skip to content

How to Setup WISE Local Development

Jump to bottom Edit New page
Hiroki Terashima edited this page Oct 26, 2020 · 20 revisions

Table of Contents

Introduction

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 https://gitter.im/WISE-Community/WISE, create an issue, or email the developer list: https://groups.google.com/forum/#!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
  • Redis. Once Redis is installed, run redis-cli config set notify-keyspace-events Egx

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

Windows:
Enable Developer Mode http://www.windowscentral.com/how-install-bash-shell-command-line-windows-10

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 https://github.com/WISE-Community/WISE.git
 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

3 Install node dependencies

 # first lift the GitHub rate limit. The command below solves this issue: https://stackoverflow.com/questions/30995040/jspm-saying-github-rate-limit-reached-how-to-fix
 $ node node_modules/jspm/jspm.js registry config github

 # then install node dependencies
 $ npm install
  1. Make wise.sh script file executable
 $ cd WISE
 WISE $ chmod u+x wise.sh
  1. Run wise.sh 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 $ ./wise.sh 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/.

    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.

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: https://github.com/WISE-Community/WISE/wiki/WISE-Administrator-Resources#First_time_getting_started

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 wise.sh with the "dev" command

 WISE $ ./wise.sh 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 wise.sh with the "reset" command.

 WISE $ ./wise.sh reset

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

 WISE $ ./wise.sh 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 "./wise.sh dev".

Here's the WISE5 design documentation and notes: https://github.com/WISE-Community/WISE/wiki/WISE5-Design-Documentation-and-Notes

To see more details about WISE5 theming and styling, visit https://github.com/WISE-Community/WISE/wiki/WISE5-Styling-and-Themes.

Coding Conventions

See https://github.com/WISE-Community/WISE/wiki/WISE5-Design-Documentation-and-Notes#coding-conventions

Committing Changes

You can use command-line git or git client tools like GitHub Client/SourceTree/Tower to commit your changes back to the GitHub project. https://help.github.com/articles/adding-a-file-to-a-repository-using-the-command-line

Please install the pre-commit hook! This will run unit tests and other checks each time you try to commit with the "git commit" command.

(in WISE checkout root directory)
WISE$ ln -s ../../pre-commit .git/hooks/pre-commit

You can bypass these check by passing in a "--no-verify" flag to the command.

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 http://wise5.org 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/
  assets
  project.json

Step 3. Make sure WISE is running:

  WISE $ ./wise.sh 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 MySQL instead of the default HSQLDB, follow these steps. Please note that we support only up to MySQL 5.8 at the moment.

  1. Download, install, and start MySQL if you don't have it already.

  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/application.properties, uncomment the properties related to mysql, and comment the properties related to hsqldb so it looks like this:

...
dbType=mysql
hibernate.connection.username=wiseuser
hibernate.connection.password=wisepass
hibernate.connection.url=jdbc:mysql://localhost:3306/wise?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8&useSSL=false
hibernate.connection.driver_class=com.mysql.jdbc.Driver
hibernate.dialect.storage_engine=innodb
hibernate.bytecode.use_reflection_optimizer=true

...

#dbType=hsqldb
#hibernate.connection.username=sa
#hibernate.connection.password=
#hibernate.connection.url=jdbc:hsqldb:file:hsqldb/wise_database;user=sa;sql.syntax_mys=true;shutdown=true
#hibernate.connection.driver_class=org.hsqldb.jdbcDriver
#hibernate.dialect.storage_engine=innodb
#hibernate.dialect=org.hibernate.dialect.HSQLDialect
#hibernate.showsql=true
...
  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 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;
  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 $ ./wise.sh 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:

 ...
 <plugin>
  <groupId>org.apache.tomcat.maven</groupId>
  ...
  <configuration>
  <port>9000</port>
 ...
 </plugin>
  1. In WISE/src/main/resources/wise.properties, change "wiseBaseURL", "curriculum_base_www", and "studentuploads_base_www":
 wiseBaseURL=http://localhost:9000/wise
 curriculum_base_www=http://localhost:9000/wise/curriculum
 studentuploads_base_www=http://localhost:9000/wise/studentuploads
  1. Start WISE
 WISE $ ./wise.sh dev

Troubleshooting

Please write to the developer mailing list if you get stuck! https://groups.google.com/forum/#!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 ./wise.sh dev

See here for details about this exception: http://stackoverflow.com/questions/18348741/message-java-lang-illegalstateexception-no-output-folder

Add a custom footer
Add a custom sidebar
Clone this wiki locally