WISE Development using Docker
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
- A Mac or Windows PC, with admin privileges
- Git 1.7+
- Docker from https://www.docker.com. You don't need to sign up or pay to use with WISE.
- GitHub account
Click on the fork button on https://github.com/WISE-Community/WISE.
You should now have your own WISE repository at https://github.com/[GITHUB_USERNAME]/WISE.
$ git clone https://github.com/[GITHUB_USERNAME]/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
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
...
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.
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.
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.
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
...
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.
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.
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
To stop WISE, issue an abort command to kill the docker process (ctrl-c).
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
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
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.
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
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
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
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.
-
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 $ docker start -i wise-dev
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