Jitbit Helpdesk

Jitbit Help Desk Software : on-premise installation manual

This is the installation manual for Jitbit Help Desk - a web based help desk software application.
Learn more about it
This manual is for Jitbit Helpdesk version 10 and later. The manual for earlier versions can be found here.

This manual will guide you through the basics of installing and operating Jitbit Helpdesk Ticketing System.

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

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:

System requirements

Platforms

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

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

Linux

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:

Installing via setup.exe

Manual installation

1. Web-application install
2. Database install

Choose one of the following options

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.

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 (this command is Ubuntu 20.04 specific).
  10. sudo apt-get update
  11. 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.

  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.

Running Jitbit Helpdesk

  1. Install .NET Runtime 6 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 6.0.4 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
            Microsoft.NETCore.App 6.0.4 [/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 and is currently in beta.

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:

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:

Linux

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

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.

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.

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:

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

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.

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

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": "[email protected], [email protected]" - 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.