Skip to content

WISE Development using Docker

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

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 create an issue on GitHub or email the developer list: https://groups.google.com/forum/#!forum/wise-dev

What you'll 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 set up

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 end-to-end (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

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