Jitbit Help Desk Software : on-premise installation manual

This is the installation manual for Jitbit Help Desk - a web based help desk software application.

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

This file will guide through the basics of installation and operation of Jitbit Helpdesk Ticketing System.

1. OVERVIEW

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

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

1.1. Tickets and Categories

Tickets (aka "issues" aka "support requests" aka "support cases") are the main entities in the help-desk system. Tickets are submitted by users and organized into categories for convenience.

1.2. User roles

Jitbit Help-Desk has four user roles:

Regular User

Manager User

Technician

Administrator

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.

2. JITBIT HELPDESK SYSTEM REQUIREMENTS

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

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.

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

2.3. PREREQUISITES

The following components are required to be installed on the server hosting Jitbit HelpDesk:

Windows: Microsoft .NET 6 Hosting Bundle (direct download)
Linux: .NET 6 (installation instructions)
Windows: 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 but CGI.
- Under "Common HTTP features" enable everything except "WebDAV" and "Directory browsing".
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).
Full-Text Search for SQL Server (this is optional, but highly recommended)
If you plan using Windows-integrated authentication - you will need "Windows authentication" role service installed in IIS. Installation instructions

Microsoft .NET 6, 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.

3. INSTALLING HELPDESK

Technically speaking, Jitbit Helpdesk is a web-app plus 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. On Windows you need "IIS" (inluded with Windows) to run the web-app, on linux you don't.

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

Full Linux installation and upgrade manual

Jitbit HelpDesk can be installed in TWO WAYS:

automatically by launching the installer file install.bat (Windows-only, recommended, if you are installing on a local server, you have terminal or physical access to)
manually (for administrator professionals, for Linux or, for example, if you want to upload Jitbit HelpDesk to a hosting environment)

3.1. INSTALLING via the installer (Windows only)

install all the prerequisites, mainly .NET 6 hosting bundle
unzip
launch install.bat (it will check if .NET 6 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.

3.2. MANUAL INSTALLATION (Windows and linux)

3.2.1. Web-application install

install all the prerequisites, mainly .NET 6 hosting bundle
unzip
copy the contents of the "helpdesk" folder to your web-server virtual directory (e.g. "c:\inetpub\wwwroot\HelpDesk" or "/var/www/helpdesk"), or upload it to your hosting environment

3.2.2. Database install

Choose one of the following options

Windows only: run the Setup.exe file from the app's folder (e.g. "c:\inetpub\wwwroot\HelpDesk\") .
OR follow these steps to create the the DB manually.
- create a new database on your SQL-server OR choose an existing database if you're upgrading.
- locate the "sql" folder within the installation folder (e.g. "c:\inetpub\wwwroot\HelpDesk\sql") and find the script files.
- Run "CreateTables.sql" for a fresh install, or "UpgradeFromOlderVersions.sql" if you are upgrading
- run the script against the database using SQL Server Management Studio
- 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

3.2.3. Run the app

Windows: configure this virtual directory as an application in IIS
Linux: run the app like this: dotnet /path/to/HelpDesk.dll. Optionally you can put the app behind an nginx reverse-proxy.

3.3. FIRST LOG IN

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"). CHANGE THESE DEFAULT PASSWORDS BEFORE USING 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.

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

4. UPGRADING FROM OLDER VERSIONS

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

4.1. Upgrading from versions 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.

4.2. Upgrading from versions 9.36 and earlier

With version 10 we've moved from .NET Framework to .NET 6 (also known as ".NET Core"). Before upgrading, please make sure you install Microsoft .NET 6 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.

4. Jitbit Helpdesk on 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-20.04 LTS. The commands for your Linux distro may be different. Jitbit Helpdesk is an ASP.NET Core app. Microsoft has a detailed manual on how to host such apps on Linux: Host ASP.NET Core on Linux with Nginx.

Prerequisites

To run Jitbit Helpdesk you'll need:

A modern Linux distribution (we use Ubuntu 20.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.
Hardware requirements depend on your expected loads, but in general they are minimal: 2CPU cores with 2GB RAM should be fine. If you intend to run the database on the same server you should get more RAM.

Installation on Linux

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:

wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
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.
sudo apt-get update
sudo apt-get install -y mssql-server
sudo /opt/mssql/bin/mssql-conf setup
You will be prompted to pick an edition. We will use Express in this example.
Accept the license terms and set a password for the SQL admin user (sa). We will need this password soon.
You should have SQL Server installed and running after that.
Install command-line tools: curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list (this command is Ubuntu 20.04 specific).
sudo apt-get update
sudo apt-get install mssql-tools unixodbc-dev

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.

/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'YOUR PASSWORD' -i CreateEmptyDB.sql
/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.

Running Jitbit Helpdesk

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

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

$ dotnet --list-runtimes
            Microsoft.AspNetCore.App 6.0.4 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
            Microsoft.NETCore.App 6.0.4 [/usr/share/dotnet/shared/Microsoft.NETCore.App]

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.
Run this command in the root directory of the unpacked folder: dotnet HelpDesk.dll. You should see Jitbit Helpdesk[2170]: HelpDesk app started.
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.

Upgrading Jitbit on Linux

This applies to both: upgrading from trial to 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:

/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.
Replace your local Jitbit files with the new ones except the appsettings.json file.
Restart the app.

5. 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 this validator before saving.

5.1 Full-Text Search

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)

Full-Text Components are optional, nothing will break without them, but installing them will improve the search speed and quality dramatically.

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

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

5.3. Helpdesk URL

Starting with version 10.15 you can find this setting in Administration - General Settings - Helpdesk URL. The old config file setting is still supported for backwards compatibility.

All outgoing email notifications about various ticket events contain a hyperlink to a ticket. The URL in those links is being initialised when Helpdesk 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 in the AppURL setting in appsettings.json. Open the appsettings.json file in the root directory of helpdesk and find "AppURL" setting and set it to the desired URL.

5.4. Storing files on disk

By default Helpdesk stores all attachments in the database. You can set it to store all attachments directly on disk:

Create folder on your hard disk, for example C:\hdfiles
Launch IIS Management Console (inetmgr.exe) and locate Helpdesk's application pool
Right click it and select "Advanced properties", then look for "Identity" property
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
Go to Helpdesk root folder (C:\inetpub\wwwroot\helpdesk by default) and locate appsettings.json file, then open it in Notepad
Find AttachmentsPath tag and set its value to the desired path.
Recycle the app pool and you're done

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

8. 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 docs can be found here: http://www.jitbit.com/helpdesk/helpdesk-api/

Email API

Email API manual can be found here: Email API

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.

"AppURL" :"http://support.yourcompany.com" - the helpdesk app will try to detect your app's URL automatically. But if you see it making mistakes from time to time - simply use this setting.

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