The Kiss system comes with its own build system, so it doesn’t use build systems such as ant, maven, or gradle. It works under Linux, Mac, Windows, etc. This included build system will make things such as downloading remote libraries, installing and configuring a web server, building Kiss, and running Kiss for development purposes easy, intelligent, and automatic. This new build system can be used in conjunction with your favorite IDE.
The build system (called it bld) is small and written in Java. Its source code is included with the Kiss source code. So, a Java compiler will be needed before anything will work. Java 8, 11, and 17 are supported.
When building the system for the first time, BLD will automatically download and cache required libraries (jar files), install and configure the development server (tomcat), build the system, and it can even be used to launch the development-mode server. After building the system the first time, application development proceeds without any need for re-compiles or re-builds.
The program that runs BLD is “bld” under Unix-like systems and “bld.cmd” under Windows. In this manual, “bld” will be shown as “./bld”. The “./” is required under Linux and Mac but not under Windows. When running on Windows, use “bld” rather than “./bld” and the same for all the other commands shown.
Note. The Kiss system includes a file named pom.xml
.
However, Kiss is not a maven project. The
pom.xml
file is only included to provide GitHub with a
list of dependencies. Unfortunately, this file sometimes confuses IDEs
into interpreting the existence of that file as the project being a
maven project. Therefore, in some instances, it is a good idea
to delete that file prior to IDE configuration.
The build.xml
file is also not used by the Kiss system per se.
It is an integration with ant for IDE integration.
This is the simplest and shortest path to a running system. It assumes:
After doing a git clone
, all that is needed is the following:
./bld develop [Linux, Mac, BSD, etc.] -or- bld develop [Windows]
This will build the system, install tomcat, deploy the app, and run the server. At this point you will be able to go your browser at the following URL:
http://localhost:8000
Be sure not to use port 8080. Although port 8080 will appear to work, you will not be able to do front-end development while the system is running. Port 8000 will allow front-end development while the system is running.
At this point, you can do all development without any build procedures. You can add or change anything on the front-end or back-end while the system is running.
All application back-end code is located under the src/main/backend
directory.
All application front-end code is located under the src/main/frontend
directory.
If you change anything in either place, the system will notice the change and deliver it with the next request.
This is a more detailed and expanded description of the same super-quick-start.
The following enumerates the steps necessary to get the system up and running:
./bld develop
http://localhost:8000
You can also debug the back-end by
attaching to the process at port 9000.
Alternatively, your IDE can be configured to run the development process entirely through it.
Once the development server is running under bld, you can stop it by hitting any key.
As shipped, there are two different environments that Kiss may run in as follows:
The Production scenario is created with a single command
(./bld war
) and produces a single war
file (located in
the work
directory) that can be deployed to your production
environment.
Before doing anything with the Development environment, it is important that you have the JAVA_HOME and JRE_HOME environment variables set correctly to the root of your JDK (Java Developer Kit). Doing this varies according to the OS you are using and various other Java installation possibilities. There are plenty of instructions on the Internet for this.
The Development environment consists of two servers. One serves the back-end REST services, and the second serves the front-end HTML, CSS, and JavaScript files. By using this method, both front-end and back-end source files can be changed on a running system and take effect immediately without any builds, compiles, server reboots, re-deploys, or file copies. (This is also true of a production environment – with a single server – when the new files are put in place.)
Back-end REST services are debugged, and edited through the IDE. Saving a source file is all that is needed to have it take effect.
The front-end (HTML, CSS, and JavaScript files) are served by a simple server supplied with the Kiss system. This server is only used during the development process. See Front-end Development. (Source code to this server is available at https://github.com/blakemcbride/SimpleWebServer) Debugging the front-end is done through the browser debugger. There is no setup, and the front-end server runs by executing a single command.
Kiss requires a few common pre-requisits as follows:
On Linux, most of these packages may be obtained utilizing the normal package manager that comes with your distribution.
The following sub-sections detail how to get those pre-requisits for Windows and Mac.
You may obtain the requirements under Windows as follows.
Correctly setting the JAVA_HOME and JRE_HOME environment variables to the root of your JDK is necessary. Setting this varies from OS to OS and also depends on where it gets installed. Instructions for setting this variable are all over the Internet.
The remaining requirements may be obtained through the Chocolatey Windows Package Manager located at https://chocolatey.org Their “community” version is free. We used their “Individual” install. The following packages should be installed after installing the choco package manager:
After installing these programs you must exit and re-start any terminals you have running.
Mac requirements may be obtained via the brew package manager available at
https://brew.sh
Once brew
is installed,you can install the remainder of the requirements with the following commands:
~/.zshrc
file and then re-start your terminal.)Kiss is located at https://github.com/blakemcbride/Kiss
It can be downloaded via the following command:
git clone https://github.com/blakemcbride/Kiss.git
Once everything has been set up, you can easily build and run the system with the following commands:
git clone https://github.com/blakemcbride/Kiss.git cd Kiss ./bld develop (or "bld develop" under Windows)
Once the system is up, you can go to the following address with your browser: http://localhost:8000
The Kiss documentation consists of three parts; this manual, the detailed back-end API documentation contained in the JavaDocs, and the detailed front-end API documentation. The JavaDocs do not come with the system, but you can generate them yourself with what is provided. See Creating JavaDocs.
This manual may be created in two forms. The first is in an HTML form. The system comes with this. You can also generate a nicely formatted PDF file with the following commands (if you have all of the formatting tools installed):
cd manual make Kiss.pdf
Updates to the HTML file are achieved with the following commands:
cd manual make
All of the documentation can be accessed with your browser. For
example, if the root of Kiss is located at
/my/home/path/kiss
then you will be able to access the three
manuals at the following URL’s:
file:///my/home/path/kiss/manual/man/index.html file:///my/home/path/kiss/work/javadoc/index.html file:///my/home/path/kiss/manual/jsdoc/index.html
The system is configured by the contents of a single file
src/main/backend/KissInit.groovy
A reboot of the web server
is required if any of the parameters in this file are changed.
Given that Kiss is for business applications, it authenticates its users. In order for this to work, there is usually a database of valid users. This information is persisted in an SQL database. Therefore a database is normally required. However, for testing purposes, if no database is configured, the system will still run and allow any username and password to succeed.
As shipped, the system comes configured as follows:
Database type | SQLite |
Host | localhost |
Database | DB.sqlite |
Database user | [empty] |
Database user password | [empty] |
Valid options for the Database type are as follows:
Support for other databases is easy to add.
setMaxWorkerThreads defines how many REST services may be processed in parallel. Service requests beyond this are placed in a FIFO queue and processed as worker threads become available. This capability drastically improves the system’s ability to handle a large number of simultaneous users.
The remaining parameters should be self-explanatory. Use the format shown in the example.
Although Kiss comes with a default demo database, another one
should be configured in live or more substantial development
environments. An SQL script file, named init.sql
, is included
with the system to initialize said database. Application specific tables
may be added to this database.
The default username is kiss, and the default password is password
On rare occasions, it is necessary to bypass authentication. In other words, be able to execute a web service without being logged in. One example of this is registering a new user. If the user isn’t already a valid user, they can’t execute services in order to register.
Kiss has a way of dealing with this scenario. This is done in
the same configuration file where all of the configuration options are
located. In the file src/main/backend/KissInit.groovy
. In
that file, you are able to specify specific web methods that may be
called without authentication. That file has an example.
It should be noted that it is recommended that something like a captcha be used to at least be confident you are communicating with a human. Additionally, it should be noted that the danger of providing unauthenticated services is somewhat mitigated by the combination of HTTPS and CORS.
Although the system may be built with the included build system (called bld) or your favorite IDE, the bld system should be used for the initial step which downloads the external dependencies (jar files).
The build system included with Kiss (called bld) has been tested on Linux, Mac, and Windows. The system also includes an Ant build file (named build.xml) that is only used for IDE integration with the included bld system.
The build system included with Kiss is written in Java and located under the src/main/core/org/kissweb/builder/ directory. This build system also includes two driver batch files / shell scripts used to build and run the build system. All that is needed to use this system is a Java compiler. (As a side note - this build system is generic and can be used to build other types of projects.)
The build process is run from the command-line. No IDE is necessary. There is no specific IDE integration. None is needed because the system is rarely built. After the first build, application development is done without any build process.
The build system, which comes in source form, must be built before it can be used to build Kiss. However, the build system gets built automatically by bld.
You can see what operations it can perform by typing:
./bld listTasks [Linux, Mac, BSD, etc.] -or- bld listTasks [Windows]
Those tasks that require prior tasks will evoke the dependent tasks automatically. The system is smart enough not to repeat tasks that are unneeded.
The main tasks that will be of interest to you are as follows:
libs
This task is only required if you intend to use your IDE to build the remainder of the system. It installs the required dependencies.
develop
This will cause the entire system to build (not repeating unnecessary
steps) and start up a tomcat instance to run the system in a
development mode. The system will be available from your local
browser at http://localhost:8000
. You may debug the
application by attaching to the running tomcat server at port
9000.
war
This will cause the system to generate the single file needed by a production system. It will end up in work/Kiss.war
Other tasks which may be useful are as follows:
clean
This task removes all files built but retains files that were downloaded from repositories (although bld caches those files anyway.)
realclean
This removes all built and downloaded files so the system should be everything you need to build it without any extraneous files
all
This performs all of the steps necessary to setup and build the system but doesn’t start up the tomcat server.
javadoc
This task creates the javadoc files that end up in work/javadoc
kisscmd
This task creates a command-line JAR that can be used in a non-web, command-line application.
This is useful when creating applications that perform various utility functions. This
JAR cannot be used in any web environment. See src/main/core/org/kissweb/Main.java
See Important and See Quick-Start Checklist.
Most IDE’s can be used to develop and debug the application. There are two way to do this as follows:
Using bld to build and run the development environment is the easiest to start off with but is somewhat klunky on an ongoing basis. Its main advantage is that it is portable and doesn’t require a lot of IDE configuration. The back-end development server is configured and started by bld by simply running ./bld develop After that, the IDE can be used to debug it by attaching to port 9000.
Kiss also comes with an ant build that simply calls the native bld program. This is useful as an intermediary between bld and the IDE since many IDE’s support ant.
Using your IDE to run the entire process is a bit tedious to initially
setup but makes the entire process simpler from that point forward.
Unfortunately, configuring your IDE is completely different for each
IDE. Instructions for setting up some of the IDEs is located under the
manual/IDE-Setup
directory.
The Kiss framework is continually enhanced. Kiss includes a mechanism to upgrade your application.
The process of upgrading your application is as follows:
git pull
./upgrade-kiss <path-to-your-application>
(Linux & macOS)upgrade-kiss <path-to-your-application>
(Windows)
Caveat
While this upgrade process upgrades the majority of the system, there are a few files that are not auto-updated to be sure not to clobber possible application-specific code that may have been added. Therefore, the following files will need to be manually verified.
src/main/core/org/kissweb/builder/Tasks.java
This file is left untouched by the upgrade process. You may have
custom tasks or modified existing tasks. Be sure to check
buildForeignDependencies()
.
libs
The upgrade process installs new or updated JAR files that are part of the Kiss system. However, you may have added application-specific JAR files. After the upgrade, be sure to manually delete any outdated JAR files that come with Kiss that have been upgraded by this process.
What you have at this point is the beginnings of your new application. Kiss is provided as a running and deployable system. It is expected that you would modify what’s there to suit your application needs.
Besides this narrative, you would need the JavaDocs located under the
work/javadoc
directory for back-end API specific documentation and
front-end API reference located in the manual/jsdoc directory.