SparkJavaStarter

After beginning to work with SparkJava, a Sinatra-like light-weight web framework for Java, I noticed that it was quite hard to be an efficient developer given the stock utilities and settings. This project is my attempt at creating a great starting point for future SparkJava projects to expedite the setup process.

Getting Started

Set up your Github OAuth Credentials

Before trying to start this web server, you need to create GITHUB_CLIENT_ID and GITHUB_SECRET credentials. You will need these later when you create your env.sh file.

Note that the env.sh file is NOT saved to github, since it contains secret information. Alternatively, I have included env.sh.example, which you should copy into env.sh and fill in properly. To do that, take these steps:

Open this page in a new tab or window (keep this page of instructions open): https://github.com/settings/developers
Click "register an application".
Fill it in similar to the picture below
The callback URL should be http://localhost:4567/auth/callback

You should be redirected to the following page. Take note of the client ID and the client secret. You will need that in the next step.

Creating and Running `env.sh`

Copy the env.sh.example into env.sh, fill in the proper values for your OAuth from above, make it executable, and run it.

cp env.sh.example env.sh
(vim/emacs/atom/nano/etc) env.sh # edit file to add your OAuth settings
chmod +x env.sh
source ./env.sh

Set Up the Application and Database

Ensure you have postgresql installed and running on localhost
Connect to your postgres instance (usually as user postgres) and run the following

CREATE DATABASE testjava;
CREATE USER testuser WITH PASSWORD 'testpassword';
GRANT ALL PRIVILEGES ON DATABASE "testjava" TO testuser;

Ensure you have java installed.
Build and run the application via ./gradlew run
That's it!

Notable Files

src/main/resources/application.conf - This is where the application configurations live.
src/main/java/me/nickbrown/sparkjavastarter/RunApplication.java - This is the main class.

Things you might need to do, and how to do them

TODO: finish the docs for this section

Adding a model
- To create a new Model, you can take a look at the existing User model in src/main/java/me/nickbrown/sparkjavastarter/models/User.java
- Essentially, you are creating a plain-old java object with some private variables that have some annotations over them
- For more advanced information on Database manipulation, check out the ORMLite documentation.
Adding a controller
Adding routes

Notable Additional Dependencies

You can check out the pom.xml file for the entire list, but here is a list of some of the java libraries that I included and my reasons for doing so:

Typesafe Config
- Allows for dynamic configuration via src/main/resources/application.conf
- We can specify static config values or pull them in from the environment
  - For example, to get $PORT from the environment, we simply write ${PORT}
- Also, we can override configs and provide fallback values.
  - If we wanted the environment port to be optional, we could specify a default and then follow up with an alternate syntax for environment vars:
    - port = 4000
    - port = ${?PORT}
Spark Handlebars Template Engine
- In order to provide dynamic HTML, we use Handlebars.
- Our Controller class actually extends from the HandlebarsTemplateEngine so that we can call helper methods from the controller class inside the templates.
  - They can even accept arguments!
ORMLite
- ORMLite lets us easily create persistent models for our application.
- Backed by JDBC, it is able to connect to multiple types of database
  - Right now, we are using Postgres in order to use Heroku in the future.
Spark-PAC4J
- Allows for flexible authentication using a variety of sources. For now, I'm using GitHub OAuth, bit you could use whatever you like.

License

See the LICENSE file for license rights and limitations (MIT).

ncbrown1/SparkJavaStarter