Advanced topics

On-premises help desk installation manual

SaaS vs On-premises

Jitbit offers both hosted and on-premises versions of the software. This installation manual is for the on-premises, "self-hosted" edition AKA "for your own server".

This is the installation manual for Jitbit Help Desk - a web based help desk software application. We will guide you through the basics of installing and operating Jitbit Helpdesk Ticketing System.

This manual is for Jitbit Helpdesk version 10 and later

This manual is for Jitbit Helpdesk version 10 and later. The manual for earlier versions can be found here.

Overview

Thank you for choosing Jitbit HelpDesk. Jitbit HelpDesk is a web-based help desk software application, designed to empower help desk teams in delivering outstanding customer service. Jitbit HelpDesk is an .NET 8 web-application with access from client computers via a web browser.

Tickets and Categories

Tickets, also known as "issues", "support requests", or "support cases", are the primary entities in the help desk system. Tickets are submitted by users and organized into categories for convenience.

User roles

Jitbit Help-Desk has four user roles:

  • Regular User - is just a regular user who submits support tickets to the system
  • Manager User - is a regular user with additional "manager" permissions. This user can view and "close" tickets from other users in the same company
  • Technician (aka "help desk agent") - is a user who is permitted (by the administrator) to handle tickets in one or more categories. A technician receives email notifications about every new ticket in a category. NOTE: To make a user a technician you have to "grant" him permissions to handle tickets in at least one category. This can be done through the category editing form in the admin section, or via the user profile editor page.
  • Administrator - most powerful user role. Helpdesk Administrator changes system settings, assigns users to categories (thus making them technicians), creates categories, adds/deletes users etc. NOTE: By default an administrator does not get notified of new issues in the helpdesk system, unless he is assigned as a "technician" to some category.

System requirements

Platforms

Jitbit HelpDesk requires a server running one of the following operating systems:

  • Microsoft Windows Server 2012 or later
  • Linux (tested on Ubuntu, centOS, WSL2, Debian)
  • Docker

Since Jitbit HelpDesk is browser based, there is no particular requirement for the client operating system. A variety of popular browsers can be used for client access to Jitbit HelpDesk including: Chrome, Firefox, MS Edge, Safari, etc.

Skills required

Please be aware that installing a web-application on a server can be a complicated task. It requires basic knowledge of how to install and administer MS SQL Server, create databases and run SQL scripts. You may also need some experience how to configure basic IIS server settings (on Windows) or Nginx web-server (on Linux). We strongly recommend going with our hosted version, please try the server-version only if you really know what you're doing.

Prerequisites

The server hosting Jitbit HelpDesk must have the following components installed.

Windows

  1. Microsoft .NET 8 Hosting Bundle (direct download)
  2. Internet Information Services (IIS) web-server with ASP.NET feature enabled.
    To enable the required features on Windows Server, do this:
    • Click "Start button"
    • in the search box, enter "Turn windows features on or off"
    • in the features window, Click: "Internet Information Services"
    • Click: "World Wide Web Services"
    • Click: "Application Development Features"
    • Check (enable) the features. Check all except "CGI".
    • Under "Common HTTP features" enable everything except "WebDAV" and "Directory browsing".
  3. If you plan on using Windows-integrated authentication - you will need "Windows authentication" role service installed in IIS. Installation instructions
  4. Microsoft SQL Server 2012 or later configured to accept both Windows and SQL authentication (the so called "Mixed Mode")
    • "SQL Server Express" edition and "SQL Server Developer" edition are free editions of MS SQL Server (developer edition has strict license terms, please check). It is available for download from the Microsoft web site. Jitbit HelpDesk uses SQL-authentication, so SQL Server has to be installed with the "Mixed Mode" authentication mode (!), with an SA-password specified ("SA" is a built-in "system administrator" user, who's password must be specified explicitly during installation).
  5. Full-Text Search for SQL Server (this is optional, but highly recommended) - all latest editions come with it included by default.

Microsoft .NET 8, Internet Information Services (IIS) and SQL Server "Express Edition" are all available at no charge from Microsoft if you do not already have the required components installed.

Linux

  • A modern Linux distribution (we use Ubuntu 22.04 in this manual)
  • Microsoft SQL Server. You can install it either on Windows or Linux. We will install SQL Server on the same machine in this manual. However, we do recommend running your database server on a separate machine for scalability. SQL Server Express editions are fine to get you started.
  • .NET 8 (installation instructions)

Docker

Installing Jitbit Helpdesk

In technical terms, Jitbit Helpdesk consists of a web application and a SQL Server database. That's it, only two main enitites. You unpack the web-app to a folder on the server, you install the database on the database server.

Windows

If you prefer a video, here is a step-by-step tutorial

Jitbit HelpDesk can be installed in two ways:

  • automatically by launching the installer file setup.exe - recommended, if you are installing on a local server, you have terminal or physical access to.
  • manually - for administrator professionals or, for example, if you want to upload Jitbit HelpDesk to a hosting environment.

Installing via setup.exe

  • install all the prerequisites, mainly .NET 8 hosting bundle
  • unzip
  • launch install.bat (it will check if .NET 8 is installed and then launch Setup.exe)
  • follow the installation instructions
  • When you get to the database creation step:
    1. setup will prompt you for the SQL-Server name. If you are using SQL Server Express Edition, please note that by default, the SQL Server Express edition is installed as a named instance (SQLEXPRESS). This means that you need to specify "(local)\SQLEXPRESS" as a server name.
    2. setup will create the "JitbitHelpDesk" database on the specified server
    3. setup will create the "JitbitHelpDeskUser" SQL-user with a randomly generated password (this password will be saved to the appsettings.json file).
    4. Note that the above steps require SQL-administrator privileges for your windows account.

Manual installation

1. Web-application install
  • install all the prerequisites, mainly .NET 8 hosting bundle
  • unzip
  • copy the contents of the "helpdesk" folder to your web-server virtual directory (e.g. c:\inetpub\wwwroot\HelpDesk or upload it to your hosting environment
  • configure the created directory as an application in IIS (inetmgr.exe)
2. Database install

Choose one of the following options

  • locate the "sql" folder within the installation folder (e.g. c:\inetpub\wwwroot\HelpDesk\sql) and find the script files.
  • Execute CreateEmptyDB.sql first, then execute CreateTables.sql on the created DB. You can use SQL Server Management Studio to do that.
  • edit the appsettings.json with any plain-text editor to change the connection string to the appropriate value (replace (local)\\ with an IP address for example). PLEASE NOTE that backslashes ("\") should be escaped with double backslashes like this server\\DatabaseName. Use the validator before saving.

Linux

In this manual, we will describe the process of installing Jitbit Helpdesk on Linux systems.

Before you proceed keep in mind that you will need to know what you are doing to run Jitbit on your own Linux server. If you do not have a competent Linux admin on hand please consider using the hosted version or installing it on Windows.

This manual is for Ubuntu. The commands for your Linux distro may be different, but fear not, Jitbit Helpdesk is an ASP.NET Core app and Microsoft has a detailed manual on how to host such apps on Linux: Host ASP.NET Core on Linux with Nginx.

1. Install SQL Server

We will install SQL Server on Linux in this example. Here is the link to official Microsoft installation guide.

Run the following commands:

  1. wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
    
  2. sudo add-apt-repository "$(wget -qO- https://packages.microsoft.com/config/ubuntu/20.04/mssql-server-2019.list)"
    
    This command is Ubuntu 20.04 specific. Look for commands for your distro in Microsoft's manuals.
  3. sudo apt-get update
    
  4. sudo apt-get install -y mssql-server
    
  5. sudo /opt/mssql/bin/mssql-conf setup
    
  6. You will be prompted to pick an edition. We will use Express in this example.
  7. Accept the license terms and set a password for the SQL admin user (sa). We will need this password soon.
  8. You should have SQL Server installed and running after that.
  9. Install command-line tools:
    curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list
    
  10. sudo apt-get update
    
  11. sudo apt-get install mssql-tools unixodbc-dev
    

2. Create the database

Download the latest Jitbit package from our site and unpack it somewhere. Go inside the unpacked directory and find sql folder. We will need to run two scripts from there: CreateEmptyDB.sql and CreateTables.sql.

  1. /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'YOUR PASSWORD' -i CreateEmptyDB.sql
    
  2. /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'YOUR PASSWORD' -i CreateTables.sql
    

NOTE: The scripts above create a default Jitbit SQL User with the default password. We recommend you change this password later and update the appsettings.json file accordingly.

3. Running Jitbit Helpdesk

  1. Install .NET Runtime 8 or later. Follow the manual for your Linux version.

  2. Check that everything is working by running dotnet --list-runtimes. You should see something like this:

    $ dotnet --list-runtimes
        Microsoft.AspNetCore.App 8.0.0 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
        Microsoft.NETCore.App 8.0.0 [/usr/share/dotnet/shared/Microsoft.NETCore.App]
    
  3. Open appsettings.json in an editor and update the connection string to look like this:

    "DBConnectionString": "user id=JitbitHelpDeskUser;data source=localhost;initial catalog=JitbitHelpDesk;password=HDPassword1"
    

    If your SQL Server runs somewhere else you will need to update the connection string accordingly.

  4. Run this command in the root directory of the unpacked folder: dotnet HelpDesk.dll. You should see Jitbit Helpdesk[2170]: HelpDesk app started.

  5. Open http://localhost:5000/ in your browser. That's it - Jitbit Helpdesk is now running.

You can run Jitbit on a different port by using dotnet HelpDesk.dll --urls http://0.0.0.0:8080.

Configuring Nginx Reverse Proxy

We will not get into detail on how to configure Nginx reverse proxy since it is out of the scope of this document. This step is optional, but it is a good idea to run a web app behind a reverse proxy. Here is the official manual from Microsoft: Configure a reverse proxy server. They have one for Apache as well.

Docker

In this manual, we will describe the process of installing and running Jitbit Helpdesk with Docker. We tested it with Docker Desktop 4.20.1.

Hosting on Docker is officially supported starting with Jitbit Helpdesk version 10.18.

If you want to run it on a Mac with an Apple silicone chip you will need to enable the "Use Rosetta for x86/amd64 emulation on Apple Silicon" setting. You can do that by going to Settings - Features in development.

Installation

  1. Download Jitbit Helpdesk from our site. It could be a trial or a full version you purchased.
  2. Unzip it to a folder where you want to run it from and go inside the "HelpDesk" folder
  3. Run docker compose up --build once you are inside the folder. Optionally run docker compose up --build -d to start in a detached mode.
  4. Once all the containers start successfully you should be able to open Jitbit on http://localhost

All Jitbit versions come with the docker-compose.yml file. Feel free to change it if you know what you are doing. For example, you can change the port from 80 to something else if you intend to run a reverse proxy in front of Jitbit.

First login

After Jitbit HelpDesk has been successfully installed, open your web-browser and navigate to the location where Jitbit HelpDesk is installed (e.g. http://myserver/HelpDesk on Windows or http://localhost:5000/ on Linux).

Unless you changed the installation scripts, Jitbit Help Desk installs with two predefined users: admin (password "admin") and client (password "client"). It is crucial to change these default passwords before starting to use HelpDesk.. Use these default users only to login for the first time and start using it.

Most pages in Jitbit HelpDesk web application have a link "get help for this page" at the bottom of the page. Clicking this link provides the most relevant in-depth information about the current page.

Fixing common problems

If you see errors when you open Helpdesk in a browser, please try these things before contacting our support:

  • Make sure you installed the ASP.NET Core hosting bundle on your Windows server (direct download) or .NET 8 on Linux (installation instructions)
  • Make sure that Anonymous-authentication module is installed and enabled in IIS for the helpdesk app! Once again: anonymous should be enabled. Otherwise you'll have problems with the API and other parts of the app
  • Depending on the type of authentication you use, check that the following authentication modules are both installed and enabled in IIS: Windows-authentication if you're using Windows-integrated auth and Forms-authentication if you're using Forms auth. All the other modules must be disabled (except for the anonymous one).
  • If you're having troubles with the mobile apps, check that API is working properly using our handy tool at http://full_helpdesk_url/api/test

Upgrading Jitbit Helpdesk

Windows

NOTE: Jitbit Helpdesk comes with an auto-update module. To upgrade your app to the latest version simply launch Setup.exe in the app's folder. It will download the latest version (if you have a licensed version it will prompt you for your password first) and update all the files. And then update the database schema. Please note that if you made changes to the source codes, this might break your changes.

Here is a step-by-step video

To upgrade your helpdesk to the latest version:

  • Download the upgrade here using your existing download-password that was emailed to you after the purchase (for registered customers only, download the trial version otherwise)
  • Backup the folder where you have your Helpdesk software installed
  • Remove all files except the "appsettings.json" file (you might get an error that "the files are in use", in that case - stop the Application Pool on Windows or abort the dotnet process on linux before proceeding).
  • Extract all the files from the downloaded archive into the Helpdesk application directory
  • Upgrade your database to the new format - run the Setup.exe file from the Helpdesk application subfolder - or run the "UpgradeFromOlderVersions.sql" script manually. The upgrade script can be found in the "/sql" subfolder. Launch SQL Server Management Studio, connect to your SQL server and execute the script against the JitbitHelpDesk database (the default name).

Linux

The following process applies to both upgrading from the trial to the full version and upgrading to the latest version. The process is the same.

There are two steps to an upgrade: updating the application files and upgrading the DB.

Download the latest version from our site, unpack it and run the following:

  1. /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'YOUR PASSWORD' -i sql/UpgradeFromOlderVersions.sql
    
    This upgrades the DB to the latest version. If your SQL Server runs somewhere else you will need to execute this script there manually.
  2. Replace your local Jitbit files with the new ones except the appsettings.json file.
  3. Restart the app.

Docker

To upgrade to a new version or transition from the trial to the full version:

  1. Download the package from our site and unzip it somewhere
  2. Replace all your old files with new ones. Keep your old appsettings.json if you changed any settings in it.
  3. While inside the folder run docker compose stop in the console
  4. After that run docker compose up --build

This process will update your database structure to the latest version automatically.

Upgrading from 10.20 and earlier

We moved from .NET 6 to .NET 8. All you need to do is install .NET 8 Hosting Bundle on Windows or .NET 8 SDK on Linux: download. You do not need to uninstall .NET 6.

Upgrading from 10.4 and earlier

With version 10.5 we've moved from .NET 5 to .NET 6. All you need to do is install .NET 6 Hosting Bundle on Windows or .NET 6 SDK on Linux: download. You do not need to uninstall .NET 5.

Upgrading from 9.36 and earlier

With version 10 we've moved from .NET Framework to .NET (also known as ".NET Core"). Before upgrading, please make sure you install Microsoft .NET 8 Hosting Bundle (direct download). After that launch Setup.exe and it should take care of the upgrade.

If you want to upgrade manually you need to move your settings from web.config to appsettings.json. That includes the database connection string, windows auth and additional settings you might've had in the "appSettings" section.

We recommend using the Setup.exe instead of a manual update.

Advanced features

Editing appsettings.json

Some of the advanced Jitbit Helpdesk features reside inside appsettings.json file in the root helpdesk directory. You can open this file with any plain text editor. You have to recyle IIS for the changes to take effect.

Appsettings.json is in JSON format. If you make a mistake the app will crash after the IIS recycle. Use the validator before saving.

By default Helpdesk searches only within tickets subject and text. You can increase the search performance and enable searching within ticket replies (comments) as well by installing Full-Text Search components on your SQL Server.

If you're not sure whether or not you have it installed, run this query on your server:

SELECT FULLTEXTSERVICEPROPERTY('IsFullTextInstalled')

If it returns "1", you're all set. If it returns "0", you need to install Full-Text components. Here are the steps you should take:

  • Install Full-Text Search components on your existing SQL Server
    • If you use SQL Server Express, there is a free edition, which includes Full-Text Search. Search for SQL Server Express with Advanced Services. You can use that installer to add full-text components to your existing SQL Server Express installation
  • Re-run the upgrade scripts from the latest version of Helpdesk on your database
  • Recycle the Helpdesk's application pool in the IIS (or simply restert IIS server)

While Full-Text Components are optional and their absence won't break anything, installing them can dramatically improve search speed and quality.

Autologin-feature

Jitbit HelpDesk supports "autologin" feature which allows users to be pre-authenticated automatically (by your parent website for example) without entering their username and password. The "autologin" feature is targeted at developers and administrators, who integrate the HelpDesk software into their existing SQL-powered websites and applications. If the user is already authenticated on your parent website (for instance) there are two options:

  1. No matter if a user is already present in the helpdesk database or not, use this link format: http://Helpdesk_Url/User/AutoLogin?username=xxx&email=yyy&userHash=HASH. The helpdesk will either create a new user account or use the existing one.

  2. In the URL above Helpdesk_Url is the full helpdesk URL, username is the user's username, email is email and HASH is calculated as follows: MD5(name + email + shared-secret + day + month). The "shared secret" is specified in the helpdesk's admin panel. Remember to specify a "strong" secret, at least 10 characters (the longer the better). The day and month values should be the current day of month, and current month formatted as TWO DIGITS, so "January 1st" should become "0101".

    You can optionally add FirstName=xxx and LastName=xxx parameters to the URL, so the newly-created helpdesk user will have the First/Last names pre-set. You can also pass CompanyName=xxx so the auto-created user will have a company assigned

When using the "autologin" feature you can optionally redirect users to the "new ticket" page. Just add "&new_ticket=1" to the link above.

Here's the up-to-date info on this feature.

Helpdesk URL

NOTE: Starting with version 10.15 you can find this (optional) setting under "Administration - General Settings - Helpdesk URL". For previous versions version see here

All outgoing email notifications about various ticket events contain a hyperlink to a ticket. The URL in those links is being initialised when Helpdesk first starts and it is taken from the URL of the very first request to the app.

For example, if you recycle the application pool and make the first request to http://localhost/helpdesk, this URL will be used in all email notifications from Helpdesk until you recycle the app pool again.

There is a way to override this behaviour by setting a desired URL like described above.

Storing files on disk

By default, Helpdesk stores all attachments in the database. However, you can configure it to store all attachments directly on the disk:

  1. Create folder on your hard disk, for example C:\hdfiles
  2. Launch IIS Management Console (inetmgr.exe) and locate Helpdesk's application pool
  3. Right click it and select "Advanced properties", then look for "Identity" property
  4. You need to grant the "identity" user full access permissions to the folder you've just created. You can read how to do it in the official manual
  5. Go to Helpdesk root folder (C:\inetpub\wwwroot\helpdesk by default) and locate appsettings.json file, then open it in Notepad
  6. Find AttachmentsPath tag and set its value to the desired path.
  7. Recycle the app pool and you're done

Windows-integrated authentication

Jitbit HelpDesk supports Windows-integrated authentication and integrating with your existing Active Directory (AD) user's catalog. To enable Windows-integrated authentication edit the appsettings.json file and un-comment this line:

"Auth": "Windows"

Also remember to check if Windows-integrated authentication is enabled in IIS directory where HelpDesk is installed. Recycle IIS after the change.

If you plan using Windows-authentication under IIS - you will need "Windows authentication" role service installed. Installation instructions.

PLEASE NOTE: that when Windows-authentication is enabled, Jitbit HelpDesk automatically adds a domain-user into the HelpDesk database when he logs in for the first time (if he is properly authenticated with his Windows-account). Also HelpDesk will try to connect to your domain-controller and populate the user's email from Active Directory.

Adding windows-user administrator

If you're installing via the "setup.exe" you'll be prompted for a Windows username to add to Helpdesk "administrators" role. If not - there's a setting in the appsettings.json file:

"WindowsAdminUsername": "DOMAIN\\User"

The username is case-sensitive. To see the exact casing of your own username execute whoami in the cmd.exe. Also note that every slash (\) should be escaped with another slash in the appsettings.json file.

API & Email API

The helpdesk app includes a "RESTful" web-service for integrating with other apps. The service address is: http://servername/helpdesk/api/

API

API docs can be found here

Email API

Email API manual can be found here: Email API

Appsettings.json validator

If you modify appsettings.json and make a mistake Jitbit will crash. We made a validator to help. Paste the file content in there and it will show you the errors.

You can find the JSON validator here.

Advanced appsettings.json settings

"WindowsAdminUsername": "DOMAIN\User"

if you're using helpdesk via Windows authentication and somehow unable to gain admin access to it - type your username into this setting

"LogErrors": true

Log helpdesk errors in the server event log

"EmailErrorTo": "admin-john@test.com, admin-pete@test.com"

Send error notifications to these addresses

"DisallowChangingAvatars": "false"

restrict users from changing their avatars (for example, if your avatars are being synched from AD)

"AttachmentsPath": "c:\hdfiles"

store helpdesk attachment in disk instead of the database. Advanced setting do not touch.

"DisableMailChecker": "true"

disable the mail-importing module for debugging purposes. Advanced, do no touch.

"AllowedFileExtensions": ".png,.pdf"

allowed file extensions for uploading.

"MailPswEncryptKey": ""

email-server passwords will be encrypted in the database using this key (if not empty). Should be 8 characters, latin letters/numbers only. Example "18d6fg81". BACKUP THIS KEY AND NEVER CHANGE IT once you set it. Otherwise your mailbox-passwords in the DB will be lost and you will have to recreate the mailboxes in the app.