Installation guide

Prerequisites

Artifacts

  • KissLog.Backend-{version}-linux-x64.zip

  • KissLog.Frontend-{version}-linux-x64.zip

Artifacts can be downloaded from https://github.com/KissLog-net/KissLog-server.

Services

  • SQL Database

  • Azure Cosmos DB

  • Storage account

  • 2x App Services

Installation

SQL Database

KissLog server does not use SQL intensively. The Basic or Standard tier should be enough to start with. If necessary, you can always upgrade it later.

If you already have an SQL server, you can skip this step.

1. Create SQL Database Server

Most of the properties remain as default. We will mention the important changes.

Basics
Server name
<any value>
Location
(Europe) West Europe <or any appropriate value>
Authentication method
Use SQL authentication
Server admin login / Password
<any value>
Networking
Allow Azure services and resources to access this server
Yes
Create SQL Database Server

2. Create SQL Database

Most of the properties remain as default. We will mention the important changes. Most of these settings can always be updated later.

Basics
Database name
kisslog-frontend (or any value)
Server
<the server created at the previous step>
Want to use SQL elastic pool?
No
Workload environment
Production
Compute + storage
Basic, 1 GB storage
Create SQL Database

Azure Cosmos DB

KissLog server uses Azure Cosmos DB very intensively. The minimum throughput used by the KissLog server (calculated in RU/s) highly depends on the frequency and volume of data you save.

The cost of the Azure Cosmos DB service is influenced by the throughput (RU/s) and by the number of replicas used.

To get started, we will use a single-region Azure Cosmos DB free tier account which covers for free a maximum of 1000 RU/s.

Create an Azure Cosmos DB account. Select Azure Cosmos DB for NoSQL.

Basics
Account Name
kisslog-database-nosql (or any value)
Location
(Europe) West Europe <or any appropriate value>
Capacity mode
Provisioned throughput
Apply Free Tier Discount
Apply
Limit total account throughput
Checked
Global Distribution
Geo-Redundancy
Disable
Multi-region Writes
Disable
Availability Zones
Disable
Networking
Connectivity method
All networks
Backup Policy
Backup policy
Continuous (7 days) (available for free)
Encryption
Data Encryption
Service-managed key
Create Azure Cosmos DB

Storage account

KissLog server uses Azure storage account for saving blob files and for reducing the workload of Azure Cosmos DB.

1. Create Storage account

Basics
Storage account Name
kisslogstorage (or any value)
Region
(Europe) West Europe <or any appropriate value>
Performance
Standard
Redundancy
Locally-redundant storage (LRS)
Advanced
Require secure transfer for REST API operations
Yes
Allow enabling public access on containers
No
Enable storage account key access
Yes
Default to Azure Active Directory authorization in the Azure portal
No
Minimum TLS version
Version 1.2
Access tier
Hot
Networking
Network access
Enable public access from all networks
Routing preference
Microsoft network routing
Data protection
Enable point-in-time restore for containers
No
Enable soft delete for blobs
No
Enable soft delete for containers
No
Enable soft delete for file shares
No
Enable versioning for blobs
No
Enable blob change feed
No
Enable version-level immutability support
No
Encryption
Encryption type
Microsoft-managed keys (MMK)
Enable support for customer-managed keys
Blobs and files only
Enable infrastructure encryption
No
Create Storage account

2. Update Lifecycle management

After the Storage account has been created, we need to setup a policy to automatically delete old blobs.

On the newly created Storage account dashboard, select the “Lifecycle management” menu from the left, then add a new rule with the following properties:

Details
Rule name
deleteAfterExpiryDate
Rule scope
Apply rule to all blobs in your storage account
Blob type
Block blobs
Blob subtype
Base blobs
Base blobs
[If] Base blobs were
Created
More than (days ago)
31 <see the note below>
Blob type
Block blobs
Blob subtype
Base blobs
[Then]
Delete the blob

Note

The value for Created more than (days ago) should be equal to (or slightly bigger) than the maximum TimeToLive property of the Request logs.

App Services

KissLog server uses 2 App Services, one for KissLog.Backend application and the second for KissLog.Frontend application.

KissLog.Backend application is responsible for processing and saving all the logs to Azure Cosmos DB. This application is CPU intensive (used for serializing/deserialzing the Azure Cosmos DB records), and uses the RAM memory for the internal queuing system.

KissLog.Frontend application is lightweight and is only responsible for displaying the user-interface.

In this tutorial we will use for both of the App Services the Free pricing plan. However, for a reliable performance and user-experience, you should scale up the App Service plans matching your usage needs.

Note

Hotizontal scaling is not currently supported by KissLog server.

Both KissLog.Backend and KissLog.Frontend applications must each be deployed to a single instace.

Create App Services

We will create two App Services, both with the same configurations:

  • kisslog-backend-code

  • kisslog-frontend-code

Basics
Name
kisslog-backend-code (or any value)
Publish
Code
Runtime stack
.NET 6 (LTS)
Operating System
Linux
Region
(Europe) West Europe <or any appropriate value>
Pricing Plan
Free F1 (Shared infrastructure)
Zone redundancy
Disabled
Deployment
Continuous deployment
Disable
Networking
Enable public access
On
Enable network injection
Off
Monitoring
Enable Application Insights
No
Create App Service

Initial deployment

1. Prepare the artifacts

Download the KissLog server package from here.

Extract the archive in a folder. Then, extract both of the resulting archives in two separate folders: KissLog.Backend and KissLog.Frontend.

Update KissLog.Backend configuration

In the KissLog.Backend folder, open the configuration file located under Configuration\KissLog.json and update the following properties:

Property
Value
Notes
KissLogBackendUrl
“URL” from the kisslog-backend-code App Service
KissLogFrontendUrl
“URL” from the kisslog-frontend-code App Service
Database.Provider
AzureCosmosDb
Database.AzureCosmosDb.ApplicationRegion
West Europe
“Write Locations” from the Azure Cosmos DB
Database.AzureCosmosDb.ConnectionString
AccountEndpoint=xxx;AccountKey=xxx;
“PRIMARY CONNECTION STRING” from the Azure Cosmos DB, “Keys” section
Files.Provider
Azure
Files.Azure.ConnectionString
DefaultEndpointsProtocol=https;AccountName=xxx;AccountKey=xxx;EndpointSuffix=core.windows.net
“Connection string” from the Storage account, “Access keys” section

Update KissLog.Frontend configuration

In the KissLog.Frontend folder, open the configuration file located under Configuration\KissLog.json and update the following properties:

Property
Value
Notes
KissLogBackendUrl
“URL” from the kisslog-backend-code App Service
KissLogFrontendUrl
“URL” from the kisslog-frontend-code App Service
Database.Provider
SqlServer
Database.ConnectionString
Server=xxx,1433;Initial Catalog=xxx;Persist Security Info=False;User ID={your_user};Password={your_password};
“ADO.NET (SQL authentication)” from the SQL Database, “Connection strings” section

2. Update the App Services

Repeat the steps below for both of the App Services.

Prepare the artifacts

Create a zip archive with the contents of KissLog.Backend folder.

KissLog Backend artifact

Stop the App Service

Make sure the App Service is stopped before uploading the new code.

Upload the artifacts

Navigate to KissLog.Backend App Service. On top right, click on “Download publish profile” button. Open the downloaded file and copy the userName and the userPWD.

KissLog Backend artifact
To deploy the application, send a POST request to https://<app_name>.scm.azurewebsites.net/api/zipdeploy.
The POST request must contain the .zip file in the message body.
Set the Basic Authentication header with the Username and Password values copied from the PublishProfile.
curl -X POST -u $kisslog-backend-code:{password} --data-binary @"<zip_file_path>" https://kisslog-backend-code.scm.azurewebsites.net/api/zipdeploy

If the update was successful, you will receive a 200 OK response status code.

The artifact can also be deployed with Postman.

Postman Authorization
Uploading KissLog.Backend code

3. Run the KissLog.Backend App Service

After KissLog.Backend App Service has been updated, start the App Service then browse to the application URL.

If everything went successful, you will see the KissLog.Backend home page.

Note

The initial startup is time consuming and can take up to a few minutes.
During the initial startup, KissLog.Backend will also create the Azure Cosmos DB database and the containers.
KissLog Backend home page

4. Run the KissLog.Frontend App Service

After KissLog.Frontend App Service has been updated, start the App Service then browse to the application URL.

If everything went successful, you will see the KissLog.Frontend home page.

Note

The initial startup is time consuming and can take up to a few minutes.
During the initial startup, KissLog.Frontend will also create the SQL database.
KissLog Frontend home page

Post deployment

Your KissLog server is running and ready to process the logs. You can update your dotnet applications to start sending the logs to the newly created KissLog.Backend AppService.

Make sure you update the configuration values, respectively the “OrganizationId”, “ApplicationId” and “ApiUrl”.

KissLogConfiguration.Listeners
    .Add(new RequestLogsApiListener(new Application(Configuration["KissLog.OrganizationId"], Configuration["KissLog.ApplicationId"]))
    {
        ApiUrl = "https://kisslog-backend-code.azurewebsites.net/"
    });
KissLog Frontend logs

Upgrade the services

In this tutorial we have used the low-pricing tier for all the Azure Services that we have created, respectively:

  • SQL Database: Basic

  • Azure Cosmos DB: 1000 RU/s

  • KissLog.Backend App Service: Free F1

  • KissLog.Frontend App Service: Free F1

Although this is enough for the KissLog server to start running, the performance and stability of the application is directly affected by the capabilities of the underlying services.

If you experience low performance, you should incrementally scale up the services. The most workload is handled by the Azure Cosmos DB service and by the KissLog.Backend App Service, and you can start with them.

Note

Hotizontal scaling is not currently supported by KissLog server.

Both KissLog.Backend and KissLog.Frontend App Services must each be deployed to a single instace.

Scale up Azure Cosmos DB

To scale up the Azure Cosmos DB service, select the “Scale” menu from the left. Increse the Throughput, then click “Save”.

Scale up Azure Cosmos DB

Scale up App Service

To scale up the App Service, select the “Scale up (App Service plan)” menu from the left. Choose a new Plan. Click “Select” to apply.

Scale up App Service

For technical support, questions or any feedback, please feel free to send us a message and we will get back to you.