Skip to main content

Installation

You can choose between different ways of using KIX 18:

  • KIX 18 On-Premises: Local installation on your own server

  • KIX 18 Cloud: Application in the KIX Cloud - without installation

Accessibility of the portals

System requirements

Important

Websocket communication takes place between the client (browser) and the front-end server. This means that intermediate systems (reverse proxy, etc.) must support websockets.

As an administrator, make sure that there is an uninterrupted and high-performance connection via web sockets between clients and the front end so as not to provoke any significant performance losses or errors. Although reverting to HTTP/s does occur, it has noticeable side effects and is explicitly not recommended .

System

For a new system, we recommend a Docker host with the following minimum requirements:

  • RAM: 8 GB

  • CPU: 4 cores

  • several high-performance, reliable hard drives (please do not use single SATA hard drives with low RPMs!)

Based on the following indicators:

  • 1,000 new tickets per month

  • 20 to 30 agent users (10 to 15 of them simultaneously)

  • up to 10,000 assets

  • 500 organizations and 500 contacts

Do you need a Docker host with:

  • RAM: 16 GB

  • CPU: at least 4 cores

  • several high-performance, reliable hard drives (please do not use single SATA hard drives with low RPMs!)

For further information, see also: https://github.com/cape-it/kix-on-premise/blob/master/deploy/linux/README.md

Server

We recommend the following operating systems for the host environments of KIX 18:

  • RHEL

  • Debian

  • Ubuntu

Make sure that Docker is stable and secure on your host system.

Note: Although newer Docker versions include Compose as a plugin, not all host operating systems use these new versions. It is therefore necessary to install Compose as a standalone version and not as a plugin.

Client

On the client side, you need a standard browser such as Firefox, Chrome, MS Edge etc. in the latest version.

Field Agent App

The Field Agent app supports the latest version of the iOS and Android operating systems.

Error handling

Problem: KIX does not start after the first installation

If you have just installed KIX with a PostgreSQL DBMS and start it for the first time, it may happen that the DB is not initialized correctly. You may find an entry similar to this in your logs:

FATAL:  no pg_hba.conf entry for host "172.20.0.4", user "kixdbuser", database "kixdb", SSL off

This is often caused by incorrect file permissions in your postgresql.conf.

  1. Please check your file permissions.

  2. Either assign the postgres user as the owner of the file or check whether other people have read access to your file by executing chmod o+r postgresql.conf.

  3. After you have checked the file permissions, stop any containers that are still running with stop.sh.

  4. Delete the corresponding Docker volume of the DB container.

    Warning

    Deleting the Docker volume leads to data loss!

    This solution only causes no data loss if the error occurs on the first start after installation!

  5. Restart your stack via start.sh.

Visit our KIX Forum for more information: KIX Forum

KIX On-Premises Installation

KIX is installed using preconfigured Docker containers and comes with its own operating environment and database. This makes it easier to use the software on different operating systems.

Only a compatible Docker version (correctly and fully installed) must be available and executable on the host environment. We therefore recommend checking whether the planned host environment supports the use of Docker before installing KIX 18.

The use of KIX 18 requires a current Docker version with Docker-Compose. Further information can be found at: docker.com or https://docs.docker.com/engine/install/linux-postinstall/.

To install KIX 18 on your own server, use the files available at KIX GitHub. For production use, we recommend installing it on Linux.

Below you will find a very concise quick guide to the on-premises installation. For detailed installation instructions, please seehttps://github.com/cape-it/kix-on-premise/blob/master/deploy/linux/README.md

Docker is operated via the console (terminal). Use the following console commands.

Notice

The user on the command line must have execution rights to the Docker service.

How to install KIX (short version)

  1. Install Docker and Docker-Compose on the host system (usually "localhost" / hereinafter: "your.docker.host"):

    Notice

    The scripts require Docker-Compose as a stand-alone installation, even if newer Docker versions already include Compose as a plugin.

  2. Retrieval of the initial Docker environment

    • cd/opt

    • git clone https://github.com/kix-service-software/kix-on-premise.git

  3. Change to the unpacked Linux or Windows directory:

    • cd kix-on-premise/deploy/linux

    • cd kix-on-premise/deploy/windows

  4. Recommendation: Create a backup copy of the following files:

    • environment

    • proxy/non-ssl.conf

    • proxy/ssl.conf

  5. SSL Setup

    Add your SSL certificates to the Docker environment in the following files:

    - Certificate:proxy/ssl/certs/server.crt
    - Key:proxy/ssl/certs/server.key

    1. In case you need a ca bundle:

      • Create the directory proxy/ssl/certs/ca-bundle

      • Copy your ca-bundle files into this directory.

      • Comment out the line with ssl_trusted_certificate in the configuration proxy/ssl/ssl.conf.

    2. Use of SSL instead of non-SSL

      • Deactivate all server entries: in the file proxy/non-ssl.conf (via comment # )

      • Activate all server entries: in the file proxy/ssl.conf (by removing # )

    Notice

    If this setup is selected, application ports defined in BACKEND_PORT , FRONTEND_PORT, SSP_PORT are used as drop-in replacements.

  6. Start or stop KIX

    • Change to the unpacked Linux or Windows directory:

      Linux:cd kix-on-premise/linux
      Windows:cd kix-on-premise/windows

    • Run the script to start the Docker service:

      Linux:./start.sh
      Windows:start.ps1

    • Run the script to stop the Docker service:

      Linux:./stop.sh
      Windows:stop.ps1

  7. Registration to KIX

    Log in to the system after starting KIX 18. If the configuration of the file environment remains unchanged, the following data will be displayed:

    • Portal access

      • Agent portal: http://your.docker.host:20001

      • Self Service Portal (KIX Pro only): http://your.docker.host:20002

    • Login data for initial registration

      User:admin
      Password:Passw0rd

  8. Then use the Setup Assistant, to set a new admin password and a super user and to carry out the basic configuration of KIX.

Using KIX Pro On-Premises

To use KIX Pro locally, you simply need to replace the public Docker registry in the file environment with your individual repository ID. We will send you the repository ID by e-mail after you have subscribed to KIX Pro.

Important

The repository ID sent to you is intended exclusively for use by you or your organization.

Therefore, do not pass on the repository ID and store it carefully and protected against unauthorized access.

If unauthorized persons come into possession of your repository ID, they could gain access to your system and your data.

  1. First install KIX Start - if not already installed (see also: KIX On-Premises Installation

  2. Open the file environment.

  3. Place a hash (#) at the beginning of the line: REGISTRY=docker- registry.kixdesk.com/public

    This will comment out the reference to the public registry so that this information is not taken into account when the program is started.

  4. In the line after next, replace <YOURREPOSITORYHERE> with your individual repository ID and remove the hash (#) at the beginning of the line.

    By removing the hash, this line is taken into account when the program is started.

  5. The result is as follows:

    # --------------------------------------------------
# basic configuration
# --------------------------------------------------
 
# the docker registry to use
#REGISTRY=docker-registry.kixdesk.com/public
 
# the following applies for KIX Pro customers
REGISTRY=docker-registry.kixdesk.com/customers/4d11xo22xxxxxxxxxxxxxxxxxxxxxxxff29
 
# the image tag to use for all application images
IMAGE_TAG=stable
...

  6. Carry out an update (see also KIX On-Premises Update)

    Notice

    If KIX Start was previously in productive use in the same version, the frontend container must be rebuilt with the following shell command so that all KIX Pro functions can be used:

    docker exec kix-frontend-1 npm run-script application-prebuild

The next time you start KIX, you can use KIX Pro.

Then use Setup Assistant to set a new admin password and a "super user" and carry out the basic configuration of KIX.

Alternatively, you can initialize KIX Pro via the console. To do this, call up the following command:

root@dockerhost:/opt/kix-on-premise/deploy/linux/# sed -i.orig 's/REGISTRY=docker- registry.kixdesk.com\/public/REGISTRY=docker-registry.kixdesk.com\/ public\nREGISTRY=docker-registry.kixdesk.com\/customers\/<YOUR_REPOSITORY_ID_HERE>/g' environment

Further information on installing KIX Pro can also be found on GitHub at:

Use with ScriptAlias

If the KIK URL contains additional path components in on-premises environments, a corresponding base route must be configured so that the KIX client can communicate correctly. This may be the case if you operate KIX via different sub-paths, e.g:

  • * host.example.org*/kix/* → Frontend agent portal

  • *host.example.org*/ssp/* → Customer portal

  • * host.example.org*/api/* → Backend

To avoid specifying ports or explicit FQDNs, you can set up KIX in on-premises environments so that ScriptAliases are also used for the Agent Portal and the Self Service Portal.

To do this, store the following environment variables with the corresponding base routes in the file environment:

  • BASE_ROUTE - for the agent portal

  • BASE_ROUTE_SSP - for the Self Service Portal

Important

Important: The configurations must always begin with a slash (/)!

# --------------------------------------------------
# base route configuration
# --------------------------------------------------
 
# Agent Portal
BASE_ROUTE=/ap
 
# Self Service Portal
BASE_ROUTE_SSP=/ssp

Make sure that the KIX paths are forwarded to the server so that the server can route the request correctly. The additional sub-path must not be forwarded to KIX, only the KIX-relevant part.

KIX.cloud environments take into account the basic route in the browser, i.e. application-specific paths follow the proxy path.

OIDC also observes the script alias configuration

Important

[de] Berücksichtigen Sie die Dekodierung von URL-Pfaden bei Proxyweiterleitungen.

[de] Bei Verwendung von Reverse Proxys können Teile der URL decodiert werden, sodass eine ungültige Route an den Frontendserver geliefert wird. So wird bspw. aus

http://localhost:100/ap/objecticons/18/image%2Fsvg%2Bxml

[de] folgende ungültige URL:

http://localhost:100/ap/objecticons/18/image/svg+xml

[de] Stellen Sie sicher, dass Sie den Reverse Proxy korrekt konfigurieren.

[de] Beispiel für Ngninx bei Basisroute Agentenportal

rewrite  ^  $request_uri;                       # get original URI
rewrite  ^/ap/(.*)$ /$1$is_args$args break;     # drop /ap, put /
return 400;                                     # if the second rewrite won't match
proxy_pass http://127.0.0.1:3000/$1;            # proxy pass to fe service

Customize STARMAN_OPTS

Your KIX installation is already delivered with a basic STARMAN_OPTS configuration. You can adapt this to the environment you are using.

If several processes/threads are to be used, you can specify the number of CPUs in the file environment.

This may be necessary if the Singe Thread Event Queue of the frontend server appears to be overloaded, even if the backend is working quickly. The log then contains the message: possible performance bottleneck.

The specified number should be based on the number of CPUs or how much the system should work. The more CPUs there are, the more workers you can specify. However, this depends on the CPUs actually in use.

If possible, insert the following lines at the beginning of the file environment:

# --------------------------------------------------
# STARMAN_OPTS configuration
# --------------------------------------------------
STARMAN_OPTS="--min_servers 5 --max_servers 20 --min_spare_servers 1 --max_spare_servers 5"

  • min_servers = minimum number of CPUs (e.g. 5)

  • max_servers = maximum number of CPUs (e.g. 20)

Important

Change the details gradually so as not to overload the system.

The more workers are defined, the more RAM is required. This means that if you have 8 CPUs with 8 GB RAM, you should not change the standard or only change it minimally despite sufficient parallelism.

Further information: https://metacpan.org/release/MIYAGAWA/Starman-0.1000/source/lib/Starman/Server.pm#L61

KIX On-Premises Update

To update an existing KIX environment, please update the KIX Docker configuration. You can find instructions on how to do this at https://github.com/cape-it/kix-on-premise/blob/master/deploy/linux/README.md

How to update KIX (short version)

  1. Update Docker configuration

    • user@DockerHost: /opt/kix-on-premise/# git pull

  2. Update KIX

    • user@DockerHost:/opt/kix-on-premise/deploy/linux# ./stop.sh

    • user@DockerHost:/opt/kix-on-premise/deploy/linux# ./update.sh

Caution

Update KIX with every update! The releases are interlinked and build on each other. Skipping versions can lead to functional gaps and malfunctions.

Note

Note that Docker takes a conservative approach to cleaning up unused objects. The objects are generally not removed, which can lead to memory overfilling. A cleanup can be carried out using the prune command. Further information can be found on the following page: https://docs.docker.com/config/pruning/.

Obtain KIX on-premises images manually

You can download your customized images to use them, for example, in environments that are not directly connected to the Internet.

Use the following commands in the console:

// Code-Platzhalter
shell> docker save docker-registry.kixdesk.com/customers/<YOUR-REPOSITORY-ID>/frontend:stable -o ./kix_frontend_stable.tar
shell> docker save docker-registry.kixdesk.com/customers/<YOUR-REPOSITORY-ID>/backend:stable -o ./kix_backend_stable.tar
shell> docker save docker-registry.kixdesk.com/customers/<YOUR-REPOSITORY-ID>/proxy:stable -o ./kix_proxy_stable.tar
shell> docker save docker-registry.kixdesk.com/customers/<YOUR-REPOSITORY-ID>/redis:stable -o ./kix_redis_stable.tar
shell> docker save docker-registry.kixdesk.com/customers/<YOUR-REPOSITORY-ID>/db:stable -o ./kix_db_stable.tar

The downloaded archives are then manually transferred to the container environment and loaded:

shell> docker load --input ./kix_frontend_stable.tar
shell> docker load --input ./kix_backend_stable.tar
shell> docker load --input ./kix_proxy_stable.tar
shell> docker load --input ./kix_redis_stable.tar
shell> docker load --input ./kix_db_stable.tar

Usage of the KIX.cloud environment

No installation is required to use a KIX.Cloud environment. KIX.Cloud is therefore also suitable as a test environment.

Apply for the provision of KIX.Cloud at www.kixdesk.com. We will send you the link to your KIX portal and the access data for the initial user (admin) by e-mail. Open the link and log in with the access data you received from us.

Then use the Setup Assistant to set a new admin password and a "Super User" and to carry out the basic configuration of KIX.

Important

Please never mark the email address support@kixdesk.com as invalid in cloud environments! Otherwise, our support team will be unable to access your system and we will be unable to assist you in the event of an error. This will result in you losing the guarantee of response and resolution times.

Installation of extensions

KIX GitHub

At KIX GitHub, we provide a range of information and scripts for KIX 18 and also for KIX 17.

In this section: