Installation guide¶

Table of contents

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

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

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

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

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

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	https://kisslog-backend-code.azurewebsites.net	“URL” from the kisslog-backend-code App Service
KissLogFrontendUrl	https://kisslog-frontend-code.azurewebsites.net	“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	https://kisslog-backend-code.azurewebsites.net	“URL” from the kisslog-backend-code App Service
KissLogFrontendUrl	https://kisslog-frontend-code.azurewebsites.net	“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.

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.

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.

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.

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.

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/"
    });

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