2.1 Important ¶

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 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, 17, and 21 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.

2.2 Super-Quick-Start ¶

This is the simplest and shortest path to a running system. It assumes:

1. you have a JDK installed
2. you have your JAVA_HOME and JRE_HOME environment variables set correctly
3. you have an Internet connection

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 to 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.

2.3 Quick-Start Checklist ¶

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:

1. See Pre-requisites
2. See Download Kiss
3. See Setup and Configuration
4. The development server can be run without an IDE by running: ./bld develop
5. Once the server starts up, you can access it on your browser by going to 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.

2.4 Runtime Environments ¶

As shipped, there are two different environments that Kiss may run in as follows:

1. Development
2. Production

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.

2.5 Pre-requisites ¶

Kiss requires a few common pre-requisites as follows:

1. Java JDK 8, 11, 17, or 21.
2. SQL Database Server — Kiss comes with the SQLite database. However, in a production system you’re likely to prefer a more substantial database server. Kiss supports a variety of SQL database servers including PostgreSQL, Microsoft SQL Server, MySQL, Oracle, and SQLite.
3. IDE — Although Kiss does not require an IDE, one is strongly recommended (e.g. IntelliJ, VSCode, NetBeans, Eclipse)
4. GIT source code control system
5. Groff — Kiss utilizes the open-source groff typesetting system in order to produce PDF reports.

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-requisites for Windows and Mac.

• Windows
• Mac

2.6 Download Kiss ¶

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

2.7 Quick Test ¶

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

2.8 Documentation ¶

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 URLs:

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

2.9 Setup and Configuration ¶

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:

Valid options for the Database type are as follows:

• PostgreSQL
• MicrosoftServer
• MySQL
• Oracle
• SQLite

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 schema.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

2.10 Bypassing Authentication ¶

On rare occasions, it is necessary to bypass authentication. In other words, one should 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 specifically 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 ensure that 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.

2.11 Building The System ¶

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 is 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.

• Using an IDE

2.12 Kiss Framework Updates ¶

The Kiss framework is continually enhanced. Kiss includes a mechanism to upgrade your application.

The process of upgrading your application is as follows:

1. Go to the directory containing a virgin clone of the Kiss framework (not your application).
2. Update your clone via: git pull
3. While remaining in the virgin Kiss clone directory (and not your application directory), run the following command:

   ./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.

2.13 What Do I Do With It Now? ¶

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 will modify what’s there to suit your application needs.

Besides this narrative, you will 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.