On-premises installation manual - Jitbit Helpdesk Docs

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

Microsoft .NET 8 Hosting Bundle (direct download)
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".
If you plan on using Windows-integrated authentication - you will need "Windows authentication" role service installed in IIS. Installation instructions
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) - 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.
Install .NET Runtime 8 or later. On Ubuntu you usually can do this by running
```
sudo apt-get update && \
    sudo apt-get install -y aspnetcore-runtime-8.0
```
For more info check this manual and follow the manual for your Linux version.

Docker

Docker engine in any form. Docker Desktop is the most convinient.

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

This chapter describes 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:

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

```
sudo apt-get update
```

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.

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

3. Running Jitbit Helpdesk

Install .NET Runtime 8 or later. On Ubuntu you can do this by running
```
sudo apt-get update && \
    sudo apt-get install -y aspnetcore-runtime-8.0
```
For more info check this manual and 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 8.0.0 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
    Microsoft.NETCore.App 8.0.0 [/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.

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

5. Auto-starting the app when server reboots

If you'd like the helpdesk app to restart when you reboot the server, you need to register it as a "service".

Create the service file:

sudo nano /etc/systemd/system/helpdesk.service

Put this into the file:

[Unit]
Description=Helpdesk

[Service]
WorkingDirectory=/path/to/app
ExecStart=/usr/bin/dotnet /path/to/app/HelpDesk.dll
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=helpdesk
User=MyUsername # set a user that the app will run under
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment="ASPNETCORE_URLS=http://127.0.0.1:5001" # set port number

[Install]
WantedBy=multi-user.target

Enable the service:

sudo systemctl enable helpdesk.service

Start the service:

sudo systemctl start kestrel-helloapp.service

Docker

This chapter describes 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

Download Jitbit Helpdesk from our site. It could be a trial or a full version you purchased.
Unzip it to a folder where you want to run it from and go inside the "HelpDesk" folder
Run docker compose up --build once you are inside the folder. Optionally run docker compose up --build -d to start in a detached mode.
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.

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 the database schema. Please note that if you made any changes to the source codes, your changes might be lost.

Here is a step-by-step video

If the automated update fails or you want to upgrade your helpdesk manually:

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)
Unpack to a temp location and either simply run Setup.exe from the temp folder OR if you want to update everything manually - continue to the next steps
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:

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

Docker

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

Download the package from our site and unzip it somewhere
Replace all your old files with new ones. Keep your old appsettings.json if you changed any settings in it.
While inside the folder run docker compose stop in the console
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 5 or 6 (depending on your current version) to .NET 8. All you need to do is install .NET 8 Hosting Bundle on Windows download or .NET 8 SDK on Linux: download. You do not need to uninstall .NET 5/6

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.

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)

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:

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.

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:

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. Remember that JSON file format requires escaping special characters like backslashes for example:

"AttachmentsPath": "C:\\path\\to\\folder", //backslashes are escaped

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

"ProxyIP": "192.168.1.1"

IP address of the reverse proxy server. If your helpdesk is running behind a reverse proxy on another machine, you need to set this value to the IP address of the reverse proxy server. Local proxy IP address should work out of the box.

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

Overview

Tickets and Categories

User roles

System requirements

Platforms

Skills required

Prerequisites

Windows

Linux

Docker

Installing Jitbit Helpdesk

Windows

Installing via setup.exe

Manual installation

1. Web-application install

2. Database install

Linux

1. Install SQL Server

2. Create the database

3. Running Jitbit Helpdesk

4. Configuring Nginx Reverse Proxy

5. Auto-starting the app when server reboots

Docker

Installation

First login

Fixing common problems

Upgrading Jitbit Helpdesk

Windows

Linux

Docker

Upgrading from 10.20 and earlier

Upgrading from 9.36 and earlier

Advanced features

Editing appsettings.json

Full-Text Search

Autologin-feature

Helpdesk URL

Storing files on disk

Windows-integrated authentication

Adding windows-user administrator

API & Email API

API

Email API

Appsettings.json validator

Advanced appsettings.json settings