JKFramework Standalone

Standalone project aims to make the software development of Java web based applications and microservices more efficient by eliminating the need of configuring or integrating with any external web server such as Tomcat or Jetty, or application server such as Glassfish, Weblogic, WebSphere or Wildfly during development time. Of course, the final product is a Java Web App Archive (WAR) which you can deploy on any Servlet container, inside container, or Application Server.

This project is mainly a wrapper around Embedded Tomcat that can enable faster development and testing of your Java web based applications.

Maven Dependency

Most likely you don’t need to include the dependency if you used one of the framework parent projects, however, if needed, the dependency is:

<!-- https://mvnrepository.com/artifact/com.jalalkiswani/jk-framework-standalone -->

If you did’nt use one of the framework parent projects, you will need to exclude Tomcat jar files from the final war to be able to run on a Servlet container using resources exclusion plugin.

Basic Usage

All what you need is to create a main class called Main or App, which shall includes only one line JKWebApplication.run();.


  1. Create Maven Project with WebStack Parent

  2. Create an App class which should looks like this:

package com.app;

import com.jk.web.embedded.JKWebApplication;

public class App {
	public static void main(String[] args) {


With the Standalone project, you will get the following benefits:

  • Tomcat instance will be configured and launched on port 8080 by default (port number can be passed as parameter if needed). The configurations will include:

    • Setting the application root to src/main/webapp

    • Adding the project’s Maven dependencies to to the war src/main/webapp/WEB-IF/lib folder.

    • Adding the project classes to the war class path at src/main/webapp/WEB-INF/classes.

    • Exclude any jars that could conflict with the embedded instance.

    • Listen to close signal at PORT+1. For example, if the instance is opened at port 8080, the close port will be 8081.

  • It will send a close signal any previous instance opened on the same port, this save you the headache of frequent Binding Exceptions.

  • Add templates files for you, which are:

    • Beans file located in src/main/webapp/WEB-INF/beans.xml, which is required to enable CDI (while beans.xml become optional in latest JEE versions, Weld still looks for it)

    • Facelet template created in src/main/webapp/WEB-INF/templates/default.xhtml.

    • Default Faces pages located at src/main/webapp/index.xhtml, which you can use as the template for your faces views/pages.

  • Finally, it will open a browser instance for your with the URL of your default page.


Here is a full example of how to run the standalone embedded web server.

package com.app;

import com.jk.web.embedded.JKWebApplication;

public class App {
	public static void main(String[] args) {

Note: This feature is for development and debugging purposes only, for production, consider a full-fledged Tomcat or Heroku webapp-runner.

After finishing development, to run your application you can easier deploy the war file to Tomcat it or run it using Heroku webapp-runner.

  • To create the war file, call mvn package on your project root folder. which could be found in the target folder. if you are using one of the framework parent apps, the final file name will be target/app.war.

  • Tomcat: To run the war file on tomcat, run tomcat, then place the war file in the webapps folder inside tomcat.

  • WebApp-Runner: To run on Heroku webapp-runner

    1. download webapp-runner.jar from here.

    2. call the following command on your app (assuming your app final name is app.war):

java -jar webapp-runner- app.war