Installation guide¶
Contents
Prerequisites¶
Artifacts
KissLog.Backend.AspNetCore.zip
KissLog.Frontend.AspNetCore.zip
The latest version of KissLog deployment packages can be downloaded from here.
Services
IIS Web server with .NET Core 3.1 Runtime installed
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
On the machine hosting the IIS server, install .NET Core 3.1 Runtime
Create two IIS applications: KissLog.Backend and KissLog.Frontend
Update the Application Pool settings for both of the applications to the following:
.NET CLR version: No Managed Code
Managed pipeline mode: Integrated
Copy into each Site folder the corresponding deploy package
Make sure that the Application Pool Identity has write permissions to the applications folders.
Initial setup¶
KissLog.Backend¶
Update KissLog.Backend configuration file located under
Configuration\KissLog.json:
KissLogBackendUrl |
|---|
Example: |
Root url pointing to the KissLog.Backend site |
KissLogFrontendrl |
|---|
Example: |
Root url pointing to the KissLog.Frontend site |
Database.MongoDb.ConnectionString |
|---|
Example: |
Connection string used to connect to the MongoDB server |
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.Frontend¶
Update KissLog.Frontend configuration file located under
Configuration\KissLog.json:
KissLogBackendUrl |
|---|
Example: |
Root url pointing to the KissLog.Backend site |
KissLogFrontendrl |
|---|
Example: |
Root url pointing to the KissLog.Frontend site |
Database.KissLogDbContext |
|---|
Example: |
Database connection string |
Authorization.HS256Secret |
|---|
Example: |
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/. |
Make a single request to the KissLog.Frontend root URL (“/”).
If the startup process went successful, you will see the home page.
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.
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.
<?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.Frontend¶
On the first run, KissLog.Frontend will try to:
Validate the configuration
Connect to MS-SQL / MySql database
Connect to
KissLog.Backendapplication 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.
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.
<?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>
