Skip to content

WISE Development using Docker

Jump to bottom Edit New page
Hiroki Terashima edited this page Mar 24, 2017 · 9 revisions

Table of Contents

Introduction

This is a quick and easy way to start developing WISE using your favorite text editor, git, and Docker. 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.

If you'd like to set up a local development environment without using Docker, please see this page: https://github.com/WISE-Community/WISE/wiki/How-to-Setup-WISE-Local-Development

What you will need

  • A Mac or Windows PC, with admin privileges
  • Git 1.7+
  • Docker, Community Edition, from https://www.docker.com. You don't need to sign up or pay to use with WISE.
  • GitHub account

Initial setup

0. Install dependencies

Check that you have installed the items on "What you'll need" section above. Make sure that Docker is running.

1. Clone WISE project locally

 $ 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. Start WISE (Mac users only)

Open a terminal, and run the following command to download and start WISE. This will download the development environment within Docker, set up WISE to use default settings, create database tables and populate them with initial values, and start WISE using maven's embedded tomcat server. The first time will ask you for your GitHub credentials because we need to bypass the GitHub rate limit: https://developer.github.com/v3/#rate-limiting. After authenticating, it and take a while to download all the dependencies, so go get some coffee while it runs!

 $ cd WISE
 WISE $ docker run --name wise-dev -it -p 8080:8080 -v $(pwd):/home/wise -v $(pwd)/.m2:/home/wise/.m2 -w /home/wise -e MAVEN_CONFIG=/home/wise/.m2 -u wise wisedocker/wise-dev
  Unable to find image 'wisedocker/wise-dev:latest' locally
  latest: Pulling from wisedocker/wise-dev
  ...
  Would you like to set up your GitHub credentials? [yes]:yes
  If using two-factor authentication or to avoid using your password you can generate an access token at https://github.com/settings/tokens. Ensure it has public_repo scope access.
  Enter your GitHub username: ENTER_YOUR_GITHUB_USERNAME_HERE
  Enter your GitHub password or access token: ENTER_YOUR_GITHUB_PASSWORD_HERE
  Would you like to test these credentials? [yes]:yes
  ok   GitHub authentication is working successfully.
  ok   Registry github configured successfully.
  ...

After some time, WISE will start running on http://localhost:8080/wise.

2. Start WISE (Windows users only)

First, make sure that Docker is running using Linux containers. Right-click on the Docker icon in the task bar. If it says "Switch to Linux containers...", click on it to switch. If it says "Switch to Windows containers...", leave it as it is.

Make sure that you are using Linux containers, not Windows

Next, make sure that your drive is shared with Docker so we can share the WISE checkout with Docker. Right-click on the Docker icon in the task bar, and click on "Settings..." to bring up the settings dialog. Check the drive to share it with Docker.

Share drive with Docker

Finally, open PowerShell, and run the following command to download and start WISE. This will download the development environment within Docker, set up WISE to use default settings, create database tables and populate them with initial values, and start WISE using maven's embedded tomcat server. The first time will ask you for your GitHub credentials because we need to bypass the GitHub rate limit: https://developer.github.com/v3/#rate-limiting. After authenticating, it and take a while to download all the dependencies, so go get some coffee while it runs!

 $ cd WISE
 WISE $ docker run --name wise-dev -it -p 8080:8080 -v ${PWD}:/home/wise -v ${PWD}/.m2:/home/wise/.m2 -w /home/wise -e MAVEN_CONFIG=/home/wise/.m2 -u wise wisedocker/wise-dev
  Unable to find image 'wisedocker/wise-dev:latest' locally
  latest: Pulling from wisedocker/wise-dev
  ...
  Would you like to set up your GitHub credentials? [yes]:yes
  If using two-factor authentication or to avoid using your password you can generate an access token at https://github.com/settings/tokens. Ensure it has public_repo scope access.
  Enter your GitHub username: ENTER_YOUR_GITHUB_USERNAME_HERE
  Enter your GitHub password or access token: ENTER_YOUR_GITHUB_PASSWORD_HERE
  Would you like to test these credentials? [yes]:yes
  ok   GitHub authentication is working successfully.
  ok   Registry github configured successfully.
  ...

After some time, WISE will start running on http://localhost:8080/wise.

3. View WISE on your browser

Open your browser and go to http://localhost:8080/wise/index.html. You should see the WISE homepage.

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.

4. Add projects

Now that you have WISE running locally, 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

5. Stop WISE

To stop WISE, issue an abort command to kill the docker 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 this docker command to start up the wise-dev Docker image.

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

 WISE $ ./wise.sh reset

Then, start WISE by running this docker command to start up the wise-dev Docker image.

 WISE $ docker start -i wise-dev

Making and testing changes to code

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 "docker start -i wise-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.

Committing changes

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 the unit tests. 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 tests

  npm 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 $ docker start -i 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

Changing port from 8080 to something else

You can manually change the port that will be used to run WISE. Let's say 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 $ docker start -i wise-dev

Using MySQL

The default set-up uses file-based HSQLDB. You can configure your setup to use MySQL with a little bit more work.

  1. Remove the wise-dev process. You'll need to stop the wise-dev process if it is running (Ctrl-C).
WISE $ docker rm wise-dev
  1. Create a local Docker network. We'll run the MySQL and WISE-dev containers on this network so they can talk to each other.
WISE $ docker network create wise-network
  1. Download and start MySQL docker image. We'll use the latest mysql image and call the container "wise-mysql". We'll also run it on the "wise-network" so it can be connected by wise-dev container later.
WISE $ docker run --name wise-mysql --net=wise-network -e MYSQL_ROOT_PASSWORD=secretPassword -d mysql:latest
  1. Connect to the "wise-mysql" container, log into mysql with root account, and create the wise_database database and users (step 8 on https://github.com/WISE-Community/WISE/wiki/How-to-Setup-WISE-on-a-Server)
# bash into wise-mysql container
WISE $ docker exec -it wise-mysql bash

# Now we're inside the wise-mysql container. Log into mysql as root user:
root@316b24bf640b:/# mysql -uroot -psecretPassword
mysql: [Warning] Using a password on the command line interface can be insecure.
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: 5.7.17 MySQL Community Server (GPL)

Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> 

# now run some queries to create wise_database and users.
# create new user wise4user, password wise4pass
mysql> create user 'wise4user'@'localhost' identified by 'wise4pass';
# create wise_database
mysql> create database wise_database default character set=utf8;
# give wise4user access to the new database
mysql> grant all privileges on wise_database.* to 'wise4user' identified by 'wise4pass';
mysql> flush privileges;  
mysql> exit;
bye

# now also exit out from the container
root@316b24bf640b:/# exit
exit
WISE $
  1. Now, create tables and import sample data into the wise_database running in the "wise-mysql" container (step 9 in https://github.com/WISE-Community/WISE/wiki/How-to-Setup-WISE-on-a-Server)
WISE $ docker exec -i wise-mysql mysql wise_database -uwise4user -pwise4pass < src/main/resources/wise_db_init.sql

Now your MySQL container is up and running with initial data! Now let's connect to this new wise-mysql container from the wise-dev container.

  1. Change settings in src/main/resources/wise.properties. Un-comment the lines with MySQL properties, and comment-out lines with HSQLDB properties. In the JDBC url, make sure to change the url from "localhost" to "wise-mysql".
hibernate.connection.url=jdbc:mysql://wise-mysql:3306/wise_database?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8
  1. Start the wise-dev container.

Mac:

WISE $ docker run --name wise-dev --net=wise-network -it -p 8080:8080 -v $(pwd):/home/wise -v $(pwd)/.m2:/home/wise/.m2 -w /home/wise -e MAVEN_CONFIG=/home/wise/.m2 -u wise wisedocker/wise-dev

Windows:

 WISE $ docker run --name wise-dev --net=wise-network -it -p 8080:8080 -v ${PWD}:/home/wise -v ${PWD}/.m2:/home/wise/.m2 -w /home/wise -e MAVEN_CONFIG=/home/wise/.m2 -u wise wisedocker/wise-dev

That's it. If all goes well, you should see WISE up and running at http://localhost:8080/wise.

Troubleshooting

Please create a ticket on GitHub or write to the developer mailing list if you get stuck! https://groups.google.com/forum/#!forum/wise-dev

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