Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
How to Setup WISE Local Development
Table of Contents
- What You Need
- Initial Set Up
- Persist Data Across WISE Restarts
- Reset Data to Initial State
- Making and Testing Changes
- Coding Conventions
- Committing Changes
- Running Unit Tests
- Running Integration Tests
- Using MySQL instead of HSQLDB
- Using a Different Port
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
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
- Download and install jdk, maven, git, and node. Set JAVA_HOME variable to point to your jdk, and add maven to your PATH.
(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 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:
- 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
2.1 Check out PortalRedesignAngular branch (Active working branch since January 2018)
$ git checkout PortalRedesignAngular
2.2 Install node dependencies
$ npm install
- Make wise.sh script file executable
$ cd WISE WISE $ chmod u+x wise.sh
- 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.
- 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.
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.
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.
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
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 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).
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 firstname.lastname@example.org. If you have problems switching versions, try restarting your computer) if not, download and install via https://dev.mysql.com/downloads/mysql
Stop WISE if it's running. To stop WISE, issue an abort command to kill the tomcat process (ctrl-c).
Open src/main/resources/wise.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 ...
- 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;
- 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
- 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.
Stop WISE (ctrl-c)
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>
- 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
- Start WISE
WISE $ ./wise.sh dev
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