/Clarkson

Web-based fuel logging dashboard

Primary LanguageTypeScriptMIT LicenseMIT

Clarkson

Clarkson is a web-based dashboard application that gives you a neat and clean interface for logging your fuel fill-ups for all of your vehicles. The application has full multi-user support, as well as multiple vehicles per user. Whenever you fill-up your car or motorcycle, keep the receipt and record the data in Clarkson.

Screenshot

Features

  • Dashboard giving you high-level statistics on your vehicle fill-ups, including:
    • Total spent on fill-ups on all your vehicles
    • Total distance traveled
    • Graphs showing fuel consumption trends
  • Add/edit/remove an unlimited number of vehicles
    • Include basic information such as Make, Model, Registration, VIN, Fuel Type
  • Add/edit/remove fuel fill-ups
    • Total cost or unit cost will be automatically calculated as you enter the data
    • Include any notes
    • Inform the app whether or not the fill-up was to the top (full tank), or if you missed any previous fill-ups
  • Choose your units - available settings:
    • Fuel Units: Litres, Gallons, or US Gallons
    • Consumption Units: MPG, L/100KM
    • Distance Units: Miles, Kilometres
    • Currency Units: GBP, USD, EUR, AUD, CAD

Running the application

Clarkson has an Angular front-end, with ExpressJS backend, connecting to a MySQL database. It uses Flyway as a means of managing incremental migrations of the database schema.

Get the dependencies

To get the application running, you'll need node and npm installed. Firstly, install the angular-cli (plus ts dependencies):

npm install -g @angular/cli ts-node typescript

Then grab all of the dependencies for the app itself:

npm install

Set up the frontend config

Depending on how you run the application, you'll need to update the src/environments/environment.prod.ts file so the frontend points to the right server URL:

export const environment = {
    production: true,
    apiBaseUrl: 'https://your-domain-here/api' // or use 'http://<local_network_ip>:3000' if not behind a reverse proxy
};

Build

Once you're happy with the endpoint in config, build the frontend:

ng build --prod

This will create a dist/ directory, which is where the frontend gets served.

Migrate the database

Before you run the application, you'll need to run a database migration using flyway. This will create the schema and initial tables/procedures that are used by Clarkson. To do this, run:

./flyway/flyway -user=<mysql_user> -password=<mysql_user> -schemas=clarkson -url=jdbc:mysql://<mysql_host_ip> migrate

Note: The -user, -password and -url values must match those that you use when running the application (see below).

JRE: Flyway is a Java tool, so requires the JRE to be available in $PATH. It is not packaged as part of this application due to variations in OS requirements.

Start the app

Finally, start the application by running:

MYSQL_HOST=<mysql_host_ip> MYSQL_USERNAME=<mysql_user> MYSQL_PASSWORD=<mysql_user> ENABLE_REGISTRATIONS=true APP_PORT=3000 node clarkson.js

Environment variables at startup:

Env Required? Used for
MYSQL_HOST Yes Points the backend to the MySQL database
MYSQL_USERNAME Yes The user with access to the clarkson schema
MYSQL_PASSWORD Yes The password for the user
ENABLE_REGISTRATIONS No Defaults to false. If set to true, allows new users to register
APP_PORT No Defaults to 3000. Changes the running port of the application

Credits