Setting Things Up
The application lives in the code/application
folder of the unit repository.
The Database
For the application to work, you will need a MariaDB database that serves the census
database.
If you want to run the database on a vagrant VM but the Java application on your own machine (this is the recommended way), make sure the VM is serving the database correctly:
- MariaDB must be installed on the VM and the census database installed as described earlier in the unit.
- Port 3306 must be exported in the
Vagrantfile
. - The
/etc/my.cnf.d/mariadb-server.cnf
must have theskip-networking
line commented out or removed.
If you want to run the database and the Java application on your vagrant VM, make sure that the following are set up:
- MariaDB must be installed on the VM and the census database installed as described earlier in the unit.
- You must export port 8000 in the
Vagrantfile
. You do not need to export port 3306 to the host, as both the database and the application using it will be running on the VM. - Either the
/etc/my.cnf.d/mariadb-server.cnf
must have theskip-networking
line commented out or removed, or insrc/main/resources/application.properties
you must add?localSocket=/var/run/mysqld/mysqld.sock
to the end of the data source URL to use a socket instead of a network (TCP) connection.
If you want to run everything on your own machine, then you need to install and run MariaDB and make sure the server is running on port 3306 (this proably means uncommenting skip-networking
in a configuration file). By default, the Java application expects the database to have a username of vagrant
and an empty password, but you can edit this in src/main/resources/application.properties
.
The React Client
The client lives in code/application/client
in the unit repository.
There are two ways to run the client. First (and recommended), install nodejs and npm if you have not done so already - this can be on a VM or on your local machine - open a terminal in the client
folder and run the following:
npm install
to download and install the dependencies. These will end up in a foldernode_modules
, which is (sensibly) excluded from the repository via a.gitignore
file in the same folder. You will get some warnings which you can ignore for now.npm run-script build
will build the application and put the results in thebuild
folder (which is also sensibly excluded from the repository).- Copy the contents of the
build/
folder to the folder../src/main/resources/static/
(the../
is relative to theclient/
folder) for the Java application to serve.
If you are actively developing the react application, then instead of building it you can use npm start
which will run a development server on localhost:3000
. The advantage of this method is that whenever you change a source file in the client folder, it will recompile and reload the react client automatically.
The Java Application
In the folder code/application
in the repository, there is a maven pom.xml
file.
- Open this folder in a terminal and run
mvn spring-boot:run
.
This will automatically download any dependencies.
You can now point your browser at localhost:8000
and you should see an overview of the regions of England. Clicking an item such as a region navigates to it, and the Details link loads the employment statistics for the current unit in a second panel on the right-hand side.
Developer Tools
For the following walkthrough of the application it is helpful to have everything running and to have the browser's F12 developer tools open in the tab running the application.
Since this is a React app, you may also want to install the React Developer Tools extension if you are using a Chrome-based browser (chrome, chromium, edge etc.). This provides extra React debugging and development integration, for example a new Components tab showing the structure of the React components on the page with their state and props.