These are the basic steps required to get PUPIL up and running:
- Install Java (JDK 8 preferably)
- Install Tomcat (version 8 works)
- Install MySql (any modern version)
- Create a mysql database
- Populate the database using the setup_db.sql script
- Edit and move the pupil webapp configuration to the appropriate Tomcat directory
- Start pupil
- Create a teacher
- Login in and test that everything works
You will need a modern Java. In theory JDK 9 could work, but it is known to be buggy on, for example, ubuntu 16.04. So out of convenience, you might want to stick with JDK 8.
You can use OpenJDK, which is available via apt. Run:
sudo apt-get install openjdk-8-jdk
If you know you have another JDK/JRE installed (if you don't know, it's unlikely. In most cases the following step is unnecessary), you might want to run:
sudo update-java-alternatives
You can download java here:
http://www.oracle.com/technetwork/java/javase/downloads/index.html
Note that you want "JDK", not "JRE". It's superfluous to get the big package with NetBeans included, but if you want to play around with it, it doesn't hurt.
You can accept all the default suggestions in the installer and just click "next".
You will want to download tomcat 8.x. It is possible a later version than 8.0 will work, but 8.0 is known to work.
Tomcat is readily available via apt. Run:
sudo apt-get install tomcat8 tomcat8-manager tomcat8-admin
This should get Tomcat up and running on port 8080.
Download tomcat from:
http://tomcat.apache.org/download-80.cgi
The installation steps are in summary as follows:
- Download the "32/64 bit windows service installer" from the download page
- Execute and install
- On the "choose components" step, also check "host manager"
- On the "configuration" step, be sure to enter user/password for an administrator account, and remember these
- On the last step you can choose to start the service. In the future you will have a "monitor tomcat" entry on your start menu, where you can start and stop tomcat.
Unless you changed something, tomcat should now run on port 8080.
Currently PUPIL is written for MySQL, but it's possible that, for example, MariaDB is compatible enough to work anyway. But out of convenience, stick with MySQL. Any modern version should work.
MySQL is available via apt. Run:
sudo apt-get install mysql-server
...and follow the instructions. No particular configuration is needed, but you will need to remember what root password you are setting for it.
Start a mysql root prompt:
mysql -u root -p mysql
Then, on the prompt, run:
CREATE DATABASE pupil;
GRANT ALL ON pupil.* TO pupil@'localhost' IDENTIFIED by 'pupil';
FLUSH PRIVILEGES;
This is an example only, for creating a database called "pupil", with a user "pupil" that has a password "pupil". This is how the default configuration is written, so if you only want to test things on your own computer this might suffice. But for production environments you should be more creative with at least the password.
MySQL is available for download at:
http://dev.mysql.com/downloads/mysql/
You want the windows msi installer. Ignore the nag about registering (there is a link for proceeding with the download at the bottom of the page).
In the installer:
- For type, choose "Custom".
- On "Select products and features", move almost all components from the right side to the left (there is a green arrow to click). On the right side you should only have:
- MySQL server
- MySQL workbench
- MySQL utilities
- On "type and networking", you can accept the defaults unless you know what you are doing. If you intend the installation to be for a production server, change "Config type" to "Server machine"
- On "accounts and roles":
- Enter and remember an administrative password
- Add a new user "pupil" and set (and remember) a password for that user
- For the rest of the steps in the installer, you can accept the defaults
You should now start "mysql workbench" (the installer allows you to do this as the final step). In the workbench do the following
- Click "local instance", and log in as admin
- Click "create new schema in the connected instance" (it's the fourth icon from the left in the toolbar) (for some reason "database" is called "schema" in mysql workbench, but "database" on a mysql prompt... Why this is so, I guess you'll have to ask a mysql dev)
- Enter "pupil" as its name, then click "apply", "apply" and "finish".
- You should now have a "pupil" entry under "schemas" in the bottom of the hierarchy to the left in the window.
- Right-click the "pupil" schema and select "set as default". You will get no feedback, but the entry should now be listed boldfaced.
In the SETUP directory, there is a file called setup_db.sql. This contains the basic definition for the initial database.
On ubuntu, run:
mysql -u pupil --password=pupil pupil < setup_db.sql
(but replace the first "pupil" with the username you used above, the second "pupil" with your password and the third "pupil" with the name of your database)
In mysql workbench:
- open the "file" menu and "open sql script".
- Browse to the "setup_db.sql" script in the SETUP folder
- Execute the script (it's the icon looking like a lightning bolt)
This step consist of two parts: Editing the database and admin settings in "WEB-INF/web.xml" and writing a configuration file for Tomcat so that it can find the web application.
For the first part: edit the file WEB-INF/web.xml. Find and change the admin username and passwords. You can set whatever you want here, this is only used for managing teachers. Also change all relevant database settings. If you named your database name/user/password "pupil", you can keep the existing values.
For the second part: In the SETUP directory you will find a sample configuration file for the webapp ("pupil.xml.sample"). You will need to edit this and set docBase to point at the PUPIL directory from the zip file. You then need to move/rename it to the configurations directory for tomcat.
On ubuntu the file should end up as /etc/tomcat8/Catalina/localhost/pupil.xml.
On windows the file should (probably) end up as C:\Program Files\Apache Software Foundation\Tomcat 8.5\conf\Catalina\localhost\pupil.xml
... but this will depend on where you installed tomcat, and might look slightly different depending on windows version and locale.
So the basic steps will (for example) be:
- Rename the pupil.xml.sample file to pupil.xml
- Edit it with an appropriate text editor (wordpad should work, notepad might run into trouble with line endings)
- change docBase to point at where you unzipped the zip file, for example "c:\PUPIL"
Tomcat will most likely need a restart in order to find the configuration. So restart Tomcat and then access the manager which will most likely be available at:
http://127.0.0.1:8080/manager/html
On windows you will already have set login and password for the manager in a configuration step above. On ubuntu, you will need to edit /etc/tomcat8/tomcat-users.xml to add a login for the manager, see
https://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html#Configuring_Manager_Application_Access
But once you have entered the manager page, you should see an entry "/pupil". If not, you have most likely missed something in the "Edit webapp configuration" step.
If the entry is there, click on it and you should arrive at the login page for PUPIL.
If everything worked thus far, you should now be able to create a teacher login. If pupil is on your local computer, navigate to:
http://127.0.0.1/pupil/admin.jsp
You will be asked for the admin username and password, which you entered in the web.xml file above.
Here you can find some self-explanatory fields for creating and changing teachers.
You should now have a configured system. Navigate to:
Here you can choose to login as a student (an example student "test" with password "test" was automatically created by the setup script).
Or you can login as the teacher you created above.
Both will have access to a very crude example project "visual1".
The docs are somewhat outdated, but should be relevant for the most part. You can find the PDF documentation here.