Bootzooka is a simple application scaffolding project to allow quick start of development for modern web based applications.
It contains only the very basic features, that almost any application needs (listed below). These features are fully implemented both on server- and client- side (as a Single Page Application). The implementations can also serve as blueprints for new functionalities.
Current user visible features:
- User registration
- Lost password recovery (via e-mail)
- Logging in/out
- Profile management
This may not sound "cool", but in fact Bootzooka is really helpful when bootstrapping a new project. This is because besides of the features mentioned it contains the whole required setup and automation of build processes both for frontend and backend. You get it out of the box which means significantly less time spent on setting up infrastructure and tools and more time spent on actual coding features in project.
Live demo is available on http://bootzooka.softwaremill.com.
Bootzooka's stack consists of the following technologies/tools:
- Scala (JVM based language)
- Scalatra (simple web framework to expose JSON API)
- H2 DB (persistence)
- Slick (query SQL database using strictly typed DSL)
- Flyway (easy schema evolution)
- AngularJS + HTML5 (browser part)
- SBT & Grunt.js (build tools)
- Swagger - for interactive API docs
It's quite simple and easy to jump into Scalatra both for Java and Scala developers. The syntax of the flow directives is straightforward and it was easy to integrate support for JSON into it. And it's written in Scala from scratch, hence seamlessly integrates with other Scala based libraries.
Why SBT and Grunt?
Bootzooka is structured how modern web applications are done these days.
The backend server exposes a JSON API which can be consumed by any client you want. In case of Bootzooka this client is a single-page browser browser application built with AngularJS. Such approach allows better scaling and independent development the server and client parts. This separation is mirrored in how Bootzooka projects are structured.
There are several sub-projects (directories) containing server-side code and one for client-side application. They are
completely unrelated in terms of code and dependencies.
CSS, HTML) and
bootzooka-backend contains the backend application. Additionaly,
bootzooka-dist is an utility module
for building a "fat jar" distribution.
In order to build and develop on Bootzooka foundations you need the following:
- Java JDK >= 7
- SBT >= 0.13
- Node.js >= 0.10.13
How to run (development)
Because (as said before) Bootzooka consists of two separate applications, in development you need to run both separately.
NOTE: This is not the case in production by default. When the final WAR package is built it contains both client and server parts in one application that can be dropped into any servlet container.
To run the backend server part, enter the main directory and type
backend-start.bat depending on your OS.
To run the frontend server part, enter the main directory and type
./frontend-start.sh. This should open
http://0.0.0.0:9090/ in your browser (frontend listens on port 9090, backend on port 8080; so all HTTP requests
will be proxied to port 8080).
For details of frontend build and architecture please refere to the bootzooka-ui README.
How to run (production)
To build an executable jar, simply run
bootzooka-dist/assembly (that is, the
assembly task in the
simply by running java:
java -jar bootzooka-dist/target/scala-2.11/bootzooka-dist-assembly-0.0.1-SNAPSHOT.jar
To build a
bootzooka-backend/package. The war will be located in
You can drop it in any servlet container (Tomcat/Jetty/JBoss/etc.)
How to execute tests
Because tests are using in-memory H2 database you don't need to have any database running on your machine.
Check out easy setup of in-memory database in
When you issue
test from SBT, tests for both server-side and client-side components are run. SBT integrates some Grunt
commands and executes tests for browser part via Grunt too.
It is now also possible to run UI tests. We have added a new project, bootzooka-ui-tests, that contains tests for UI. This project is not part of the normal build and hence these tests must be run manually. To do it, simply run sbt in the bootzooka project directory, switch to bootzooka-ui-tests project and invoke the tests task.
$ sbt [info] Loading project definition from /Users/pbu/Work/bootzooka/project/project [info] Loading project definition from /Users/pbu/Work/bootzooka/project [info] Compiling 1 Scala source to /Users/pbu/Work/bootzooka/project/target/scala-2.11/sbt-0.13/classes... [info] Set current project to bootzooka-root (in build file:/Users/pbu/Work/bootzooka/) > project bootzooka-ui-tests [info] Set current project to bootzooka-ui-tests (in build file:/Users/pbu/Work/bootzooka/) > test
Alternatively you can run a single test using the test-only task.
> test-only uitest.ScalaRegisterUITest
These tests are written using WebDriver and you need Firefox 20 to properly run them.
Generally during development you'll need two processes:
- sbt running the backend server (e.g. using
~;container:start; container:reload /)
- grunt server which automatically picks up any changes
We are using the best IDE right now: IntelliJ IDEA. To generate an Idea project start
sbt and run
Useful sbt commands
compile- compile the whole project
test- run all the tests
project <sub-project-name>- switch context to the given sub-project, then all the commands will be execute only for that sub-project, this can be also achieved with e.g.:
container:start- starts the embedded Jetty container (backend)
~;container:start; container:reload /- runs container (backend) and waits for source code changes to automatically compile changed file and to reload it
Database schema evolution
With Flyway, all you need to do is to put DDL script within bootzooka-backend/src/main/resources/db/migration/ directory.
You have to obey the following naming convention:
# stands for unique version of your schema.
Configuration is done through the Typesafe Config library.
Reference configuration is stored in the
reference.conf file. You can either modify that file directly or override
it using system properties (see Typesafe Config's readme on how to do that).
- To have e-mail sender working please provide smtp details (host, port, password, username).
Interactive API docs
The interactive API docs (i.e. Swagger UI) are available at
<Bootzooka URL>/api-docs. The raw JSON produced by Swagger lives at
Project is licensed under Apache 2.0 License which means you can freely use any part of the project.