Installation guide

Prerequisites

Artifacts

  • KissLog.Backend.AspNetCore.zip

  • KissLog.Frontend.AspNetCore.zip

The latest version of KissLog deployment packages can be downloaded from here.

Services

Installation

MongoDB

For instructions installing MongoDB server, please check the official tutorial.

MS-SQL / MySql

We will not cover the installation guide for these services. There is a high possibility that the existing server will already have a running instance of MySQL or MS-SQL server.

IIS web applications

  1. On the machine hosting the IIS server, install .NET Core 3.1 Runtime

  2. Create two IIS applications: KissLog.Backend and KissLog.Frontend

  3. Update the Application Pool settings for both of the applications to the following:

Application Pool settings
.NET CLR version: No Managed Code
Managed pipeline mode: Integrated
KissLog.Frontend Application Pool KissLog.Backend Application Pool
  1. Copy into each Site folder the corresponding deploy package

KissLog.Frontend Site contents
KissLog.Backend Site contents
  1. Make sure that the Application Pool Identity has write permissions to the applications folders.

Initial setup

KissLog.Backend

  1. Update KissLog.Backend configuration file located under Configuration\KissLog.json:

KissLogBackendUrl

Example: "http://kisslog-backend.myapp.com/"

Root url pointing to the KissLog.Backend site

KissLogFrontendrl

Example: "http://kisslog.myapp.com/"

Root url pointing to the KissLog.Frontend site

Database.MongoDb.ConnectionString

Example: "mongodb://localhost:27017"

Connection string used to connect to the MongoDB server

KissLog.Backend configuration
  1. Make a single request to the KissLog.Backend root URL (“/”).

If the startup process went successful, a 200 OK "Running" response will be returned.

This will bootstrap all the necessary components, including configuration validation and MongoDB database generation.

KissLog.Backend Startup

KissLog.Frontend

  1. Update KissLog.Frontend configuration file located under Configuration\KissLog.json:

KissLogBackendUrl

Example: "http://kisslog-backend.myapp.com/"

Root url pointing to the KissLog.Backend site

KissLogFrontendrl

Example: "http://kisslog.myapp.com/"

Root url pointing to the KissLog.Frontend site

Database.KissLogDbContext

Example: "Data Source=192.168.16.11;Initial Catalog=KissLog_Frontend;UID={_username_};PWD={_password_};"

Database connection string

Authorization.HS256Secret

Example: "J6UVNS3EKG46O1S1OVJ59OZ8DH3KEP"

Represents the authentication JWT signature key.

In order to authenticate to this KissLog application, the user must provide a JWT token which has been signed with the same key (HS256Secret) that has been specified here.

The authentication JWT can be created programmatically, or online using https://jwt.io/.

KissLog.Frontend configuration
  1. Make a single request to the KissLog.Frontend root URL (“/”).

If the startup process went successful, you will see the home page.

KissLog.Frontend Startup

Troubleshooting

KissLog.Backend

On the first run, KissLog.Backend will try to:

  • Validate the configuration

  • Connect to MongoDB server

If any of these steps fails, the application will not start. In that case, you need to check the logs, as they will give you a hint about the current issue.

Internal logs

All the application errors are logged under the \Logs folder.

If there is no \Logs folder, most probably IIS doesn’t have write permissions. In that case, manually create the \Logs folder, execute the startup process again and check the logs.

KissLog.Backend logs folder
KissLog.Backend logs

IIS logs

If the application fails to start and no internal logs can be found, activate the IIS logs.

To activate the IIS logs, edit web.config and set stdoutLogEnabled to true.

After updating the web.config file, execute the startup process again and check the logs.

web.config
<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <location path="." inheritInChildApplications="false">
        <system.webServer>
            <handlers>
                <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
            </handlers>
            <aspNetCore processPath="dotnet" arguments=".\KissLog.Backend.AspNetCore.dll"
                hostingModel="inprocess"
                stdoutLogFile=".\logs\stdout"
                stdoutLogEnabled="true" />
        </system.webServer>
    </location>
</configuration>
KissLog.Backend IIS logs

KissLog.Frontend

On the first run, KissLog.Frontend will try to:

  • Validate the configuration

  • Connect to MS-SQL / MySql database

  • Connect to KissLog.Backend application using an HTTP connection

If any of these steps fails, the application will not start. In that case, you need to check the logs, as they will give you a hint about the current issue.

Note

KissLog.Frontend will try to create the database automatically.

If the sql user doesn’t have permissions, you will need to create the database manually.

The create database script is located under \Logs\CreateDatabaseScript.txt file.

Internal logs

All the application errors are logged under the \Logs folder.

If there is no \Logs folder, most probably IIS doesn’t have write permissions. In that case, manually create the \Logs folder, execute the startup process again and check the logs.

KissLog.Frontend logs folder
KissLog.Frontend logs

IIS logs

If the application fails to start and no internal logs can be found, activate the IIS logs.

To activate the IIS logs, edit web.config and set stdoutLogEnabled to true.

After updating the web.config file, execute the startup process again and check the logs.

web.config
<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <location path="." inheritInChildApplications="false">
        <system.webServer>
            <handlers>
                <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
            </handlers>
            <aspNetCore processPath="dotnet" arguments=".\KissLog.Frontend.AspNetCore.dll"
                hostingModel="inprocess"
                stdoutLogFile=".\logs\stdout"
                stdoutLogEnabled="true" />
        </system.webServer>
    </location>
</configuration>
KissLog.Frontend IIS logs