Setting up Developer Environment

This is a guide for setting up the developer environment for DataSpread as of release v0.5. The instructions also include additional information for help installing some required software.

Required Software

• Apache Maven >= 3.5.0
• Apache Tomcat >= 8.5.4
• IntelliJ = Ultimate
• Java Platform (JDK) >= 8
• NodeJS >= 10.9
• PostgreSQL >= 10.5, < 11
• PostgreSQL JDBC driver = 42.1.4

Instructions

1. Install NodeJS (version 12 recommended), Java Platform (JDK), and Apache Maven.

2. Install PostgreSQL == 10.

   • For Mac, Postgres.app is a quick way to get PostgreSQL working, so you can skip installing PostgreSQL directly.

     • Install the version of Postgres.app that supports PostgreSQL v10. Open the application and create a new v10 PostgreSQL server, if there is not one already, by expanding the sidebar and pressing the + button on the bottom left.

     

   • For Windows and other operating systems, install PostgreSQL and launch the application.

3. Create a database and a user who has access to the database within PostgreSQL. Record and remember the database name, username, and password. Typically when you have PostgreSQL installed locally, the password is blank.

   PostgreSQL commands to refer to for help (exclude beginning and ending `, replace words enclosed in <>):

   `\du`: Lists users
   
   `\l`: Lists databases
   
   `\q`: Quit postgres
   
   `\c <DATABASE> <USER>`: Connect to database <DATABASE> as user <USER>. Can be called when already connected to a database.
   
   `CREATE DATABASE <DATABASENAME>;`: Creates database with name <DATABASENAME>
   
   `CREATE ROLE <USERNAME> WITH SUPERUSER LOGIN PASSWORD '<PASSWORD>';`: Creates a superuser with username <USERNAME> and password <PASSWORD>
   
   `GRANT ALL PRIVILEGES ON DATABASE <DATABASENAME> TO <USERNAME>;` : Gives user of name <USERNAME> all privileges on database of name <DATABASENAME>
   
   `REVOKE ALL PRIVILEGES ON DATABASE <DATABASE> FROM <USER>; DROP USER <USER>;`: Removes all privileges from <USER> on database <DATABASE> and deletes the user.
   

   1. Start any PostgreSQL v10 server e.g. postgres, which should bring you to a Terminal window

   

   2. Create a database with any name. Ex. CREATE DATABASE dataspread;

   3. Create a superuser with any name. User accessing the database must be a superuser. Ex. CREATE ROLE dataspreaduser WITH SUPERUSER LOGIN PASSWORD '';

   4. Grant privileges to the user on the database. Ex. GRANT ALL PRIVILEGES ON DATABASE dataspread TO dataspreaduser;

   

   5. These credentials will be used for the Apache Tomcat configuration

4. Install Apache Tomcat. You can use the guide here. Make a note of the directory where tomcat is installed. This directory is known as TOMCAT_HOME in all documentation.

   1. Download the latest version of Tomcat 9 from https://tomcat.apache.org/download-90.cgi. You can click on the tar.gz link under Binary Distributions > Core.

   2. You can skip the steps in the guide, but note the directory you want tomcat to be installed in.

5. Update the Tomcat configuration. You need to update the following file, which is present in the conf folder under TOMCAT_HOME folder.

   1. Update conf/context.xml by adding the following text at the end of the file before the closing XML tag.

      <Resource name="jdbc/ibd" auth="Container"
                type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
                url="jdbc:postgresql://127.0.0.1:5432/<database_name>"
                username="<username>" password="<password>"
                    maxTotal="20" maxIdle="10" maxWaitMillis="-1" defaultAutoCommit="false" accessToUnderlyingConnectionAllowed="true"/>
      

   2. Replace <database_name>, and with your PostgreSQL installation's database name, user name and password respectively. Using credentials (blank password) from earlier example:

      <Resource name="jdbc/ibd" auth="Container"
                type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
                url="jdbc:postgresql://127.0.0.1:5432/dataspread"
                username="dataspreaduser" password=""
                    maxTotal="20" maxIdle="10" maxWaitMillis="-1" defaultAutoCommit="false" accessToUnderlyingConnectionAllowed="true"/>
      

6. Copy postgresql-42.1.4.jar (Download from here) to lib folder under TOMCAT_HOME. It is crucial to have the exact version of this file.

7. Install IntelliJ Ultimate. You can get the educational account by applying here.

8. Check out this repository if you haven't already and open the directory using IntelliJ.

9. Enable Tool Bars and Tool Buttons in the IntelliJ view. On the right toolbar, click on Maven project and import the dependency.

   1. Open the Maven toolbar on the side. Click the execute maven goal button and run mvn clean install

   

   

   2. Under the Run menu, click Edit Configurations..., add a new configuration using the + button, and select Tomcat Server > Local.

   

   Under the Deployment section, use the webapp:war exploded as the artifact with the Application Context field set to /. Setting the Application Context to any other value may lead to the app displaying a blank screen when deployed.

10. Now you are ready to run the DataSpread program. Run the application and a new webpage will automatically pop up. If not, you can also type in http://localhost:8080 in any browser. When running DataSpread, make sure the PostgreSQL server you specified in the Tomcat conf/context.xml is running in the background.

This is what the application looks like when it is running!

License

MIT