Jira Align installation

Atlassian supports the current on-premise version and the immediately prior release. Current version information can be found in the release calendar.

Prerequisites

Jira Align deployment consists of a web server and an SQL database. It can be installed in a single-server or in a multiple-server configuration for load balance and scalability.

Before you begin, review and make sure your environment meets or exceeds the hardware and software requirements.

Hardware requirements

Single-server configuration

Multiple-server configuration: Web application server

Multiple-server configuration: Database server

Software requirements

These requirements apply to both single-server and multi-server configurations.

Webserver requirements

Database server requirements

Access and privilege requirements

These requirements apply to both a single-server and a multi-server configuration.

Web server

To properly install all dependencies and configure the Jira Align Web server, it is required to have Windows System Administrator privileges

Database server

• For initial deployment: required to have the SQL sysadmin role
• For version upgrades: required to have db_owner role on the 2 Jira Align databases
• For regular operations: SQL user roles may be reduced to db_datareader and db_datawriter

Install Internet Information Services (IIS) and required features

You can install Internet Information Services (IIS) with either a manual or automated process.

Manual installation

To install IIS and its required features manually:

1. On the Windows server, open Server Manager and select Add Roles and Features.
2. Install Web Server (IIS) with the following selections in bold:
   • Web Server
     • Common HTTP Features
       • Default Document
       • Directory Browsing
       • HTTP Errors
       • Static Content
       • HTTP Redirection
     • Health and Diagnostics
       • HTTP Logging
       • ODBC Logging
     • Performance
       • Static Content Compression
       • Dynamic Content Compression
     • Security
       • Request Filtering
       • Basic Authentication
     • Performance
       • .NET Extensibility 4.8
       • ASP
       • ASP.NET 4.8
       • ISAPI Extensions
       • ISAPI Filters
     • Management Tools
       • IIS Management Console
       • IIS 6 Management Compatibility
         • IIS 6 Metabase Compatibility
   • 
3. Download and install additional software required to run Jira Align:
   1. .NET Framework 4.8 Runtime 
   2. ASP.NET Core Runtime and .NET Runtime 6.0.29

   3. ASP.NET Core Runtime Windows Hosting Bundle Installer 8.0.4 
      Note: Microsoft support for .NET 6 will end in November 2024. As a result, the initial installation instructions will install .NET 8 web hosting while including both .NET 6 and .NET 8 runtimes. 

      Microsoft SQL Server Command Line Utilities installation is required to run SqlCmd by the user logged in performing the installation or upgrade. Install msi, which is available at https://www.microsoft.com/en-us/download/details.aspx?id=53591 (SQL Server 2019).

   4. OLE DB Driver (MSOLEDBSQL) for SQL Server, versions 18.6.5, 18.6.6, or 18.6.7 
   5. Microsoft IIS URL Rewrite module - Suggested download is English x64 version 

Automated installation

To perform an automated installation of IIS and all required features:

1. Create a file named webserver.ps1 with the following content:

   # Import the Server Manager Module to be able to use the Add-WindowsFeature cmdlet
   Import-Module ServerManager
   # List of features to install
   $features = @(
       "Web-Server",
       "Web-WebServer",
       "Web-Common-Http",
       "Web-Security",
       "Web-Request-Monitor",
       "Web-Static-Content",
       "Web-Default-Doc",
       "Web-Dir-Browsing",
       "Web-Http-Errors",
       "Web-Http-Redirect",
       "Web-App-Dev",
       "Web-ISAPI-Ext",
       "Web-ISAPI-Filter",
       "Web-ASP",
       "Web-Health",
       "Web-Http-Logging",
       "Web-ODBC-Logging",
       "Web-Basic-Auth",
       "Web-Performance",
       "Web-Stat-Compression",
       "Web-Dyn-Compression",
       "Web-Mgmt-Tools",
       "Web-Mgmt-Console",
       "Web-Mgmt-Compat",
       "Web-Metabase",
       "Web-Asp-Net45",
       "Web-Net-Ext45"
   )
   # Loop through each feature and install it
   foreach($feature in $features){
   Add-WindowsFeature -Name $feature
   }
   
   # Check if Chocolatey is installed
   if (-not (Get-Command choco -ErrorAction SilentlyContinue)) {
       # Install Chocolatey
       Set-ExecutionPolicy Bypass -Scope Process -Force;
       [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; 
       iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
   }
   
   choco install dotnet-6.0-aspnetruntime --version 6.0.29
   choco install dotnet-6.0-runtime --version 6.0.29
   choco install dotnet-8.0-aspnetruntime --version 8.0.4
   choco install dotnet-8.0-runtime --version 8.0.4
   choco install dotnet-8.0-windowshosting --version 8.0.4
   choco install iiscrypto-cli
   choco install urlrewrite
   Invoke-WebRequest -Uri 'https://go.microsoft.com/fwlink/?linkid=2238605' -Outfile msoledb18_6_6.msi
   msiexec /i 'msoledb18_6_6.msi' IACCEPTMSOLEDBSQLLICENSETERMS=YES /q
   choco install sqlserver-cmdlineutils --version 15.0.4298.1
       

2. Open Powershell with administrator privileges.

3. Change the execution policy with the following command:

   Set-ExecutionPolicy Unrestricted

4. Execute the webserver.ps1 file you created in step 1. The installation of all components and features will take several minutes, and there will be multiple prompts for confirmation that must be accepted.

Installation instructions

1 - Set up folders for Jira Align installation

To create the necessary folder structure for installing Jira Align:

1. Connect to your Jira Align web server.
2. Create a folder named C:\[YOURCOMPANYNAME] by replacing [YOURCOMPANYNAME] with your organization’s initials or name.

3. Inside the C:\[YOURCOMPANYNAME] folder, create another folder named Releases.

   Example: C:\YOURCOMPANYNAME\Releases

4. Inside the C:\[YOURCOMPANYNAME]\Releases folder, create another folder named [VERSION], where [VERSION] represents the release version number. Use this folder to store and run the installation and upgrades.
   • Example: C:\YOURCOMPANYNAME\Releases\10.122.2.14
5. Inside the C:\[YOURCOMPANYNAME]\ folder, create a new folder named [CUSTOMER_DATABASE]. Replace [CUSTOMER_DATABASE] with the name of your database.
   • Example: C:\YOURCOMPANYNAME\CUSTOMER_DATABASE
6. Also inside the C:\[YOURCOMPANYNAME]\ folder, create a new folder named JiraAlign. This will be the root of the IIS site.
   • Example C:\YOURCOMPANYNAME\JiraAlign
7. Inside the C:\[YOURCOMPANYNAME]\[CUSTOMER_DATABASE] folder, create a new folder named BackofficeService. This is where the Windows email service will run from.
   • Example: C:\YOURCOMPANYNAME\CUSTOMER_DATABASE\BackofficeService
   • For more details, check out the Set up the Backoffice service section below.
8. Copy the provided Jira Align .zip file into the C:\[YOURCOMPANYNAME]\Releases\[VERSION] folder and extract its contents to the same location. This folder will serve as the root for relative paths mentioned later in this article.
9. If you're connecting Jira Align to an external system like Jira:
   1. Inside the C:\[YOURCOMPANYNAME] folder, create a new folder named Jira. This will be the folder which the Windows connector service runs from.
   2. Example: C:\YOURCOMPANYNAME\Jira

2 - Set up Jira Align databases

Create the [CUSTOMER_DATABASE] database

Replace [CUSTOMER_DATABASE] with the database name of your choosing.

To set up a database:

1. Open SQL Server Management Studio.
2. Right-click on Databases and select New Database.
3. In the displayed window, update the Database name field with the name of your choice. In the image below, the database is named YOURDATABASENAME.
   
4. Configure other database properties, like File Path, according to your organization's policies.
5. Select OK.
6. If you prefer using an SQL query, run the following with the required privileges to create the database:
   • CREATE DATABASE [CUSTOMER_DATABASE]
7. Next, find the C:\[YOURCOMPANYNAME]\Releases\[VERSION]\Sources\Backups\NewDB_AgileCraft.sql file in the installation package folder and run it on your newly created [CUSTOMER_DATABASE] database.

Notes:

• There shouldn't be any errors while executing this SQL script. However, you may encounter warnings due to the creation of database objects and their dependencies that might not exist before the script's successful completion.
• If you experience any issues with database connections, try restarting the SQL Server Service

3 - Create an application database user

An SQL database login and an SQL user with the db_owner role are required to install and update Jira Align. After the installation or update is complete, you can change the SQL user’s privilege to db_datareader and db_datawriter only by following the steps in the Change SQL user to minimum privileges section below.

To create the SQL database user through the user interface:

1. Open SQL Server Management Studio.
2. In the Object Explorer, expand the Server item.
3. Right-click on the Security folder and choose New Login.
4. Enter a new login name [DATABASE_USER] in the Login name field.
   • Example: JiraAlignSqlUser
5. Choose SQL Server Authentication.
6. Set the Default database to [CUSTOMER_DATABASE] and Default Language to English in the corresponding menus.
   
7. Select User Mapping on the left side menu.
8. Select the [CUSTOMER_DATABASE] database and check the box for the db_owner role.
   

Alternatively, you can create the SQL database user through an SQL script. Create and run the following script, replacing the sample values with your real ones:

• JIRAALIGNSQLUSER : replace with your desired SQL user name
• SAMPLEPASSWORD : replace with the desired password
• YOURDATABASENAME: replace with your database name

USE [master]
GO
CREATE LOGIN [JIRAALIGNSQLUSER] WITH PASSWORD=N'SAMPLEPASSWORD', DEFAULT_DATABASE=[YOURDATABASENAME], DEFAULT_LANGUAGE=[us_english], CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF
USE [YOURDATABASENAME]
GO
CREATE USER [JIRAALIGNSQLUSER] FOR LOGIN [JIRAALIGNSQLUSER]
ALTER ROLE [db_owner] ADD MEMBER [JIRAALIGNSQLUSER] 

Change SQL user to minimum privileges

After the initial deployment or update is complete, you can lower the SQL user privileges to the minimum required: db_datareader and db_datawriter.

To change the SQL user privileges through the user interface:

1. Open SQL Server Management Studio.
2. In the Object Explorer, expand the server name.
3. Expand the Security folder.
4. Expand Login.
5. Right-click the user to be updated and select Properties.
6. Select User Mapping.
7. Select the [CUSTOMER_DATABASE] database, remove the db_owner, and add db_datareader and db_datawriter. In the example image below, [CUSTOMER_DATABASE] is named YOURDATABASENAME.
   

Alternatively, you can update the SQL User roles through an SQL script. Create and run the following script, replacing the sample values with your real ones:

• JIRAALIGNSQLUSER: Replace with the SQL user being edited
• YOURDATABASENAME: Replace with your database name

USE [YOURDATABASENAME]
GO
ALTER ROLE [db_datareader] ADD MEMBER [JIRAALIGNSQLUSER]
ALTER ROLE [db_datawriter] ADD MEMBER [JIRAALIGNSQLUSER]
ALTER ROLE [db_owner] DROP MEMBER [JIRAALIGNSQLUSER]

4 - Set up the web server

Set up an IIS site to enable your web server. To set up the IIS site:

1. Launch Server Manager.
2. Choose IIS.
3. Right-click the server and select Internet Information Services (IIS) Manager.
4. Open the Sites folder.
5. Right-click Sites and select Add Web Site.
   Important: Make sure to install Jira Align in the IIS site's root directory.
6. Enter your [YOURCOMPANYNAME] in the Site Name field of the Add Website screen.
7. Select the ellipses (...) button next to the physical path, and find the Jira Align folder from the Initial Folder Setup section C:\[YOURCOMPANYNAME]\JiraAlign.
   
8. Select OK.
9. Set up Bindings for your instance's URL, and choose the HTTPS type (only if you have certificates).
10. Pick the SSL certificate installed earlier.
11. Enter 443 under Port, and select OK.
12. In the IIS manager, find and double-click on the ASP icon under the IIS section.
    1. Select Limits Properties to expand it.
    2. Adjust the Maximum Request Entity Body Limit value to 20,000,000.
    3. Increase the Response Buffering Limit to 67,108,864.
    4. Select Session Properties to expand it.
    5. Modify the Session Timeout. We recommend 01:30:00, but you can use a setting of your choice.
    6. Select Apply.
    7. Close the window by selecting your website.
       
13. On the left menu, click Application Pools and choose the Application Pool website [YOURCOMPANYNAME] that you created earlier.
    1. Select Advanced Settings from the Actions bar on the right side.
    2. Make sure the .NET CLR Version is set to v4.0.
    3. Expand the Process Model section and change the Idle Time-out (minutes) value to 90.
       
    4. Select OK.

5 - Connect the web application to the database

To connect the web application to the database:

1. Copy the global.asa and web.config files from C:\[YOURCOMPANYNAME]\Releases\[VERSION]\Source to C:\[YOURCOMPANYNAME]\JiraAlign.
2. Open C:\[YOURCOMPANYNAME]\JiraAlign\web.config using a text editor.

3. In the connectionStrings section, add the "Main" node after the <clear /> tag

   <add name="Main" connectionString="Data Source={Data Source};Initial Catalog={Initial Catalog};Integrated Security=False;User Id={SQL User Name};Password={SQL Password};Encrypt=yes;TrustServerCertificate=True;MultipleActiveResultSets=True;" />

4. Edit the Main connection (remove curly brackets):
   1. Data Source: Enter the IP address or Name of your database server.
      • Example: 192.168.1.111
   2. Initial Catalog: Replace [CUSTOMER_DATABASE] with the actual name of your customer database.
      • Example: YOURDATABASENAME
   3. User ID: Replace [DATABASE_USER] with your SQL username. Refer to the Create an application database user section above.
      • Example: JIRAALIGNSQLUSER
   4. Password: Enter the password for your SQL username. Refer to the Create an application database user section above.
      • Example: SAMPLEPASSWORD

   5. <add name="Main" connectionString="Data Source=192.168.1.111;Initial Catalog=Yourdatabasename;Integrated Security=False;User Id=JIRAALIGNSQLUSER;Password=SAMPLEPASSWORD;Encrypt=yes;TrustServerCertificate=True;MultipleActiveResultSets=True;" />

5. Save and close the file.
    

Note: Keep in mind that after running the deployment scripts in the following section, the database connection information will be moved to C:\[ROOT_DIRECTORY]\_CUST\web.config. If you need to modify this file later on, you'll need to restart IIS for the changes to take effect.

6 - Install the Jira Align web application and database changes

To install the latest version of Jira Align:

1. Find the file named deploy-only-CUSTOMERNAME.bat in C:\[ROOT_DIRECTORY]\Releases\[VERSION]\... and rename it by replacing CUSTOMERNAME with your organization’s name (e.g., deploy-only-Yourcompanyname.bat).
   • Example: C:\YOURCOMPANYNAME\Releases\10.122.2.14\deploy-only-yourcompanyname.bat
2. Open the renamed file in a text editor.
3. Change the CUSTOMERNAME command line argument to the IIS site name you used earlier (e.g., YOURCOMPANYNAME); keep the quotes in the command.
   
4. Open a command prompt as an administrator. Check this link for more info: Start a Command Prompt as an Administrator.
5. In the command prompt, go to your deploy-only-[YOURCOMPANYNAME].bat file FOLDER.
6. Run the file by entering deploy-only-YOURCOMPANYNAME.bat.
7. Confirm the displayed values by entering Y and pressing Enter. This will update the database, deploy website files, and make necessary permission changes.
8. Wait for the Successfully processed message.
9. Close the command prompt.
10. Check log files in [ROOT_DIRECTORY]/Releases/[VERSION]/Sources/Log local. If any unchecked files are larger than 0 KB, look for errors and contact the Jira Align Support Team if needed.

Set up the Backoffice service

The Backoffice service is a set of tasks that provide important operations. Email functionality, processing financial calculations, and maintenance of snapshots and the session state table are enabled by the service. Backoffice must be active and running for your on-premise site to function correctly. 

To set up the Backoffice service:

1. Copy all files from C:\[ROOT_DIRECTORY]\Releases\[VERSION]\Sources\BackofficeService to the C:\[ROOT_DIRECTORY]\[CUSTOMER_DATABASE]\BackofficeService folder you created earlier.
2. Open the AgileCraft.Backbone.dll.config file in C:\[ROOT_DIRECTORY]\CUSTOMER_DATABASE]\BackofficeService folder using a text editor.
3. Edit the Main connection (remove curly brackets):
   1. Data Source: Enter the IP address or name of your database server.
      • Example: 192.168.1.111
   2. Initial Catalog: must be [CUSTOMER_DATABASE]
      • Example: YOURDATABASENAME
   3. User ID: Replace [DATABASE_USER] with your SQL username. Refer to the Create an application database user section above.
      • Example: JIRAALIGNSQLUSER
   4. Password: Enter the password for your SQL username. Refer to the Create an application database user section above.
      • Example: Atlassian@321

   5. <add name="Main" connectionString="Data Source=192.168.1.111;Initial Catalog=YOURDATABASENAME;Integrated Security=False;User Id=JiraAlignSqlUser;Password=Atlassian@321;Application Name=Backoffice;Encrypt=yes;TrustServerCertificate=True;MultipleActiveResultSets=True;" />

4. Open ServiceTasks.BackOffice.dll.config in C:\[ROOT_DIRECTORY]\[CUSTOMER_DATABASE]\BackofficeService using a text editor.
5. Set the smtp_from_email_address value to the email address you want to send emails from. Make sure this email can send mail through the host or relay in the next step.
6. Update the SMTP email relay server settings for the attributes host="127.0.0.1", port="25", and enableSsl="false" that Jira Align will use to relay email through.
7. Optionally, add userName and password attributes if you need to authenticate to the SMTP host or relay. These values will be encrypted when the Backoffice Windows service starts.
   1. If you're unsure about email relay settings, ask your IT administrator.
   2. For details on supported SMTP relay settings, visit this article: smtp Element (Network Settings).

8. To install the Backoffice service as a Windows service, run the following command in the C:\[ROOT_DIRECTORY]\[CUSTOMER_DATABASE]\BackofficeService folder using the command prompt with administrator privileges:

   install.bat --task BackOffice --instance Yourcompanyname

   1. To uninstall the Windows Service later, run

      uninstall_AgileCraft_BackOffice_Yourcompanyname.bat

      in a command prompt with administrator privileges. Alternatively, if the file does not exist, run these commands instead:

      SET SERVICE_NAME=AgileCraft_BackOffice_Yourcompanyname
      uninstall.bat

9. In the Windows Services Management Console, set the service's startup type to Automatic (Delayed Start). The service name will be AgileCraft_Backoffice_Yourcompanyname. Once the product is installed or upgraded successfully, you can start this Windows service.
10. You can now manually start the Backoffice service or let it start automatically upon server reboot.

Set up connectors

To Install a new Jira connector:

1. Copy all files from C:\[YOURCOMPANYNAME]\Releases\[VERSION]\Sources\Jira to a new folder: C:\[YOURCOMPANYNAME]\Jira.
2. Open the file C:\[YOURCOMPANYNAME]\JIRA\AgileCraft_Jira.exe.config.
3. Update the "Main" database connection string with the following information:
   1. Data Source: Enter the IP address or Name of your database server.
      • Example: 192.168.1.111
   2. Initial Catalog: Replace [CUSTOMER_DATABASE] with the actual name of your customer data database.
      • Example: YOURDATABASENAME
   3. User ID: Replace [DATABASE_USER] with your SQL username. Refer to the Create an application database user section above.
      • Example: JIRAALIGNSQLUSER
   4. Password: Enter the password for your SQL username. Refer to the Create an application database user section above.
      • Example: SAMPLEPASSWORD

   5. <add name="Main" connectionString="Data Source=192.168.1.111;Initial Catalog=Yourdatabasename;Integrated Security=False;User Id=JiraAlignSqlUser;Password=Atlassian@321;Encrypt=yes;TrustServerCertificate=True;MultipleActiveResultSets=True;" />

4. Change the value of the WMSConnectorID key to 1 if you're setting up your first connector.

5. To install the Jira connector service as a Windows service, run the following command in the C:\[YOURCOMPANYNAME]\JIRA folder using the command prompt with administrator privileges:

   install.bat --instance Yourcompanyname --connector-id 1

   replacing 1 with the value of your WMSConnectorID.

   • To uninstall the Windows Service later, run uninstall_AgileCraft_Yourcompanyname_1.bat with administrator privileges. Alternatively, if the file does not exist, run these commands instead:

     SET SERVICE_NAME=AgileCraft_Yourcompanyname_1
     uninstall.bat

6. Don't start the connector yet; set the service's startup type to Manual.
7. Coordinate with Jira Align to configure the synchronization settings between Jira Align and Jira.
8. Once configured, change the service's startup type to Automatic (Delayed Start) for smooth operation during server reboots.
9. You can now manually start the Jira connector service; it will also start automatically when the server reboots.

To Install additional Jira connectors:

1. Create a separate folder for each new connector (e.g. C:\[ROOT_DIRECTORY]\JIRA2 or C:\[ROOT_DIRECTORY]\JIRA3).
2. Repeat the steps above, making sure that the WMSConnectorID value in the AgileCraft_Jira.exe.config file on each folder matches the connector ID in the UI.

To log into Jira Align for the first time after initial installation, contact the Jira Align Support team.