Azure App Service installation

Jitbit Helpdesk runs on Azure App Service with an Azure SQL Database. It is a regular ASP.NET Core app, so there is no special installer: you deploy the files from the downloaded package yourself, using zip deploy, FTP or your CI/CD pipeline.

This page covers what is specific to App Service. For everything else (appsettings.json, search, authentication) see the self-hosted installation manual.

Creating the web app

We recommend Windows App Service. Linux works too, see the notes at the end of this list.

• Runtime stack: .NET 10
• Plan: Basic tier or higher, because Always On is not available on Free and Shared. A Premium v3 P1v3 plan (2 vCPU, 8 GB RAM) is a good starting point for production. B2 or P0v3 is enough for a test environment. If CPU or memory usage stays high, move to a bigger plan.
• Platform: 64-bit
• Always On: on. Email polling and all background jobs run inside the web app, so the app must stay loaded.
• Web sockets: on. Real-time ticket updates use web sockets, and they are off by default on Windows App Service.
• HTTPS Only: on, minimum TLS version 1.2
• Time zone (optional): nightly maintenance jobs (closing and deleting old tickets, purging logs) run by server time, which is UTC on App Service. Add the WEBSITE_TIME_ZONE app setting if you want them to run at night in your time zone.

On Linux App Service, also:

• add the ASPNETCORE_FORWARDEDHEADERS_ENABLED app setting with the value true, so the app knows that requests come in over HTTPS
• set the startup command to dotnet HelpDesk.dll if it is not detected automatically

Creating the database on Azure SQL

The CreateEmptyDB.sql script from the package does not work on Azure SQL Database, because it creates a server-level login and switches databases with USE. Do this instead:

1. Create a database in the Azure portal, for example JitbitHelpDesk. Allow the web app to connect to it, either with the "Allow Azure services and resources to access this server" firewall option or with VNet integration and a private endpoint.
2. Connect to the new database (not master) as the server admin, using SQL Server Management Studio or sqlcmd, and create a user for the helpdesk:

   CREATE USER JitbitHelpDeskUser WITH PASSWORD = 'a-strong-password';
   ALTER ROLE db_datareader ADD MEMBER JitbitHelpDeskUser;
   ALTER ROLE db_datawriter ADD MEMBER JitbitHelpDeskUser;
   

3. Run sql/CreateTables.sql from the package against the database. If your database is not named JitbitHelpDesk, delete the use JitbitHelpDesk line at the top of the script first.

   sqlcmd -S yourserver.database.windows.net -d JitbitHelpDesk -U youradmin -P 'YOUR PASSWORD' -I -i sql/CreateTables.sql
   

The helpdesk user only needs to read and write data. Database upgrades are run with the admin account, see Upgrading.

Configuring the app

Instead of editing appsettings.json, put the configuration on the web app's Configuration page (environment variables). Values set there override appsettings.json, survive redeployments and keep passwords out of the deployed files.

• Under Connection strings, add DBConnectionString with the type SQLAzure. Use the "ADO.NET (SQL authentication)" connection string from the database's "Connection strings" page in the Azure portal, with the helpdesk user and password from the previous step.
• Add any other appsettings.json key as an app setting with the same name, for example LuceneIndexPath or MailPswEncryptKey (see Advanced appsettings.json settings).

After the first login, go to "Administration - General Settings" and set the Helpdesk URL to your public address (your custom domain or https://yourapp.azurewebsites.net), so links in email notifications point to the right place.

Persistent storage

Files written to the local disk of an App Service instance can disappear on restart, on redeployment or when Azure moves the app to another machine. Only the D:\home folder (/home on Linux) is persistent. Never point any path into site\wwwroot, deployments can overwrite it.

• Attachments are stored in the database by default. This is the simplest option on App Service: there is nothing on disk to lose, and Azure SQL backups cover everything. The trade-off is database size and Azure SQL storage cost. If you prefer to store files on disk, set AttachmentsPath (see Storing files on disk) to a folder under D:\home, for example D:\home\data\JitbitHelpdesk\Attachments. On Linux, use /home/data/JitbitHelpdesk/Attachments (make sure WEBSITES_ENABLE_APP_SERVICE_STORAGE is not set to false) or an Azure Files share mounted to the app. Keep in mind that D:\home counts towards your plan's storage quota. Azure Blob Storage is not supported.
• Search index: the default search index location is not persistent on App Service. Set LuceneIndexPath to D:\home\data\JitbitHelpdesk\SearchIndex (or /home/data/JitbitHelpdesk/SearchIndex on Linux). If the index is lost, the helpdesk rebuilds it in the background on the next start, and search results are incomplete until it finishes.
• Everything else (settings, users, knowledge base, logo) is stored in the database.

Email

• Azure blocks outgoing connections on port 25. Use port 587 or 465 for your SMTP server, or connect Office 365 via oAuth in the email settings.
• Email polling runs every 15 seconds inside the web app, which is why Always On must be enabled. Background jobs start about 90 seconds after the app starts, so after a restart or redeployment there is a short pause before new emails are picked up. Emails stay in the mailbox until they have been turned into tickets, so a restart does not lose any mail.

Upgrading

The Setup.exe auto-updater does not work on App Service. To upgrade manually:

1. Download the new version and unpack it.
2. Back up the database. Azure SQL keeps automatic backups, but a manual copy of the database right before the upgrade makes rolling back easier.
3. Take the app offline. On Windows, upload an app_offline.htm file into site\wwwroot: this stops the app while deployment tools keep working. On Linux, do the next two steps right after one another. The app may show errors for a minute in between.
4. Run sql/UpgradeFromOlderVersions.sql from the new package against the database, using the admin account:

   sqlcmd -S yourserver.database.windows.net -d JitbitHelpDesk -U youradmin -P 'YOUR PASSWORD' -I -i sql/UpgradeFromOlderVersions.sql
   

   The app does not upgrade the database by itself. The script is safe to run more than once.
5. Deploy the new files, replacing the old ones. If your settings are stored on the web app's Configuration page, you can deploy the default appsettings.json from the package as is. Otherwise, keep your existing appsettings.json.
6. Delete app_offline.htm (if the deployment did not remove it) and open the helpdesk.

If you use deployment slots and a staging slot points to the production database, add the DisableAllJobs app setting with the value true to the staging slot and mark it as a "deployment slot setting". Otherwise both slots process the same mailboxes and jobs.

Test and staging environments

A separate test or staging environment counts as another installation. The 10, 25, 50 and 100 agent plans include one production installation. The Unlimited agents plan allows unlimited installations within your company, see server licensing explained. There is no license activation, so recycled or replaced App Service instances do not affect your license.

If you create a test environment from a copy of the production database, add the DisableMailChecker app setting with the value true before starting it. Otherwise it starts fetching emails from your production mailboxes. Also turn off email notifications in the test helpdesk ("Administration - Email settings"), so real users don't get emails from it. If production uses MailPswEncryptKey, use the same value in the copy.

Not available on App Service

• Windows-integrated authentication: App Service can't join your domain. Use SAML single sign-on with Microsoft Entra ID instead.
• Active Directory user sync, unless the app can reach your domain controller (for example, through VNet integration and a VPN or ExpressRoute connection).