This guide contains the steps for setting up and configuring a new server for running the AgWare Maven Web Application. If you already have the application installed and are upgrading, please see Upgrade Guide.


Maven is not a desktop software. It is a Browser based application that needs to be installed on a server running Microsoft IIS (Internet information Server).


The default install for Maven is c:\AgWare\Maven. We do not install into the Program Files directory as we do with our desktop application. This is because Maven modifies files inside the install directory and doing that in Program Files is not encouraged. The files include the application.json file, log files, and report template files.


WINDOWS SERVER SETUP


Install IIS using the Windows Server Manager by adding the IIS Role. Make sure to include the Windows Authentication and WebSocket Protocol features.



NET FRAMEWORK


Maven is a .NET application. However, it is a self-contained application and we do not require a specific runtime to be installed.


INSTALL THE .NET  WINDOWS HOSTING BUNDLE


  1. Install the .NET Core Windows Server Hosting bundle on the hosting system. The bundle installs the .NET Core Runtime, .NET Core Library, and the NET Core Module. The module creates the reverse proxy between IIS and the Kestrel server. If the system doesn’t have an Internet connection, obtain and install the Microsoft Visual C++ 2015 Redistributable before installing the .NET Core Windows Server Hosting bundle.


    • Navigate to the .NET All Downloads page.
    • Select the latest non-preview .NET Core runtime from the list and click the All .NET x.x downloads. Unless you intend to work with preview software, avoid runtimes that have the word “preview” in their link text.
    • On the ASP.NET Core runtime download page under Windows, select the Hosting Bundle Installer link to download the .NET Core Windows  Hosting bundle.


  1. Important!  If the hosting bundle is installed before IIS, the bundle installation must be repaired. Run the hosting bundle installer again after installing IIS.
  2. To prevent the installer from installing x86 packages on an x64 OS, run the installer from an administrator command prompt with the switch OPT_NO_X86=1.
  3. Restart the system or execute net stop was /y followed by net start w3svc from a command prompt. Restarting IIS picks up a change to the system PATH made by the installer.



Download the AgWare Maven installer and db-update tool from https://www.uaar.net/downloads/
Be sure to download the Update Script that matches the version of Maven that is being installed.

Create a new Database


Open SQL Server Management Studio


  1. In Object Explorer, connect to an instance of the SQL Server Database Engine and then expand that instance.

  2. Right-click Databases, and then select New Database.


  1. In New Database, enter a database name


  1. To create the database by accepting all default values, select OK; otherwise, continue with the following optional steps.


  1. To change the owner name, select (...) to select another owner.


  1. To change the default values of the primary data and transaction log files, in the Database files grid, select the appropriate cell and enter the new value. 


  1. To change the collation of the database, select the Options page, and then select a collation from the list.


  1. To change the recovery model, select the Options page and select a recovery model from the list.


  1. To change database options, select the Options page, and then modify the database options. 


  1. To add a new filegroup, select the Filegroups page. Select Add and then enter the values for the filegroup.


  1. To add an extended property to the database, select the Extended Properties page.


  1. In the Name column, enter a name for the extended property.


  1. In the Value column, enter the extended property text. For example, enter one or more statements that describe the database.


  1. To create the database, select OK.





Run the Database Update Tool


The application DB-Update.exe  is a tool we use to create and/or update the database tables. Download and save the most current db-update.zip file in a folder of your choice on your machine.

Unzip the folder an In a command window, type db-update and hit the “Enter” key, you will be prompted to enter a server name (the name of your SQL Server including the instance), and a database name:



When successfully running the tool in the command window you should see some output that looks like this:




If an error occurs during the database creation or update, the issue will be displayed in the command window.

RUN THE AGWARE MAVEN INSTALLER





SETTING UP A NEW MAVEN INSTANCE


To create a new Maven instance, open the Maven Admin Tool Maven.Admin.exe. The default location is C:\AgWare\Maven\Admin



This will open the Maven Configuration Utility.

If you are missing any required components, you will be notified of what is missing.



If all requirements are met, the Maven Configuration Utility will default to the Config tab with a prompt to get started.


Click Add Application to begin setting up the Maven instance.



  1. Add Application - Adds a new instance of Maven.


  1. Site - Allows to add the instance to a subdomain or leave it a is for the default website.


  1. Application Pool - Is the AppPool that this instance will use.


  1. Name - Is the name of the instance. For the example shown the path to the instance will be https://YourCompanyWebSite/Maven.


  1. Identity - Is a user service account assigned to the database with UAAR_WebService permissions (See Security). This is the user service account that the instance will run under.


  1. Database Connection String - Clicking Edit will bring up a JSON file to configure the database string. 


  1. Save - Saves the instance.


Editing the JSON File


Below is the default JSON that is generated with the instance. I have changed: 


  1. Change Data Source to the Server\Instance name (*Note The backslash is escaped by adding an additional backslash).


  1. Change Catalog to the database name.


  1. Change Autoupdate to true (this allow for updating Maven without having to run the script against the database).



Save the changes in the JSON file and then click Save in the Maven Configuration Utility.





Before accessing Maven, give the UAAR_WebSevice user the UAAR_WebSevice permission.
 





CONFIGURING THE DATABASE CONNECTION STRING


There is an application settings help file at C:\AgWare\Maven\Web\appsettings.help.txt that is created when Maven is installed. .
This document has all the possible configuration options for Maven.


    // Authentication: Configure options for Authenticating Users within Maven.

    "Authentication": {

      // Method: Set the Authentication Method to use.

      //   Options: "Windows", "Azure"

      "Method": "Windows",

      // AzureAd: Configure settings for using Azure Active Directory Authentication.

      //   Applies only if "Method" is set to "Azure".

      //   See "Maven Azure AD Setup" guide for details on use.

      "AzureAd": {

        "Instance": "https://login.microsoftonline.com/",

        "Domain": "localhost",

        "TenantId": "<Tenant ID>",

        "ClientId": "<Client ID>",

        "CallbackPath": "/signin-ad",

        "ClientSecret": "<Client Secret>"

      }

    

    },

    // ConnectionStrings: Configure Connection Strings for the database used by Maven.

    "ConnectionStrings": {

      // DefaultConnection: The only Connection String currently used by Maven. Set to the

      //   Connection String of the Sales Database.

      //   Example:

      //     "Data Source=(local);Initial Catalog=Maven;Integrated Security=True;MultipleActiveResultSets=true"

      //   **Note: Backslashes must be escaped using another backslash, i.e. there must be 2 backslashes between

      //   the server name and the instance name.

      //   For more examples see www.connectionstrings.com/sql-server

 "DefaultConnection": "Data Source=(local);Initial Catalog=AgWare;Integrated Security=True;MultipleActiveResultSets=true;TrustServerCertificate=True"

    },

    // Database: Database configuration options.

    "Database": {

      // Autoupdate: Configure whether or not to have Maven automatically update the database

      //   to the latest schema on startup. If 'false', the databse will have to be updated

      //   manually using db-update.exe before Maven will run.

      //   Options: true, false

      "Autoupdate": true,

      // CommandTimeout: Time, in seconds, to wait while executing database queries.

      "CommandTimeout": 30

    },

{

    // Application: Configure options for the Maven web application.

    "Application" : {

        // Name: Optional name to display in the site banner.

        "Name": "QA",

        // Color: Optional color to use for the site header.

        //   Accepts any valid CSS color value.

        "Color": "lightyellow"

    },

    // GoogleMaps: Options for using Google Maps in Maven. There are currently no options

    //   here that should be modified.

    "GoogleMaps": {

      "APIKey": "AIzaSyAL4labvfmcYYvCpZbggv5-1-TdiKqoDhE"

    },

    // Logging: Options for configuring the Logs Maven writes to for troubleshooting.

    "Logging": {

      "LogLevel": {

        // Default: The level of detail that Maven writes to its Logs.

        //   Options: "Warning", "Information"

        //   Set to "Information" to have Maven log more detailed info to the logs. This will

        //   result in larger log files on the server.

        "Default": "Warning"

      },

      "PathFormat": "Logs/Maven_Log_{Date}.txt",

      "FileSizeLimitBytes": null,

      "RetailedFileCountLimit": 14

    },


    // SignalR: Options for configuring the SignalR Hub connections.

    "SignalR": {

        "EnableDetailedErrors": false,

        "MaximumReceiveMessageSize": 268435456

    },


    // SupportBee: Configuration of the SupportBee API used to submit log files and errors

    //   to AgWare.

    "SupportBee": {

      // Api: Configuration of the API endpoint to use. These values should not be modified.

      "Api": {

        "BaseAddress": "https://agware.supportbee.com",

        "AuthToken": "gzSxCAqsoM5UKo7dvVxC"

      },

      // Customer: Customization of the Customer information that is sent with SupportBee tickets.

      "Customer": {

        // DefaultEmail: Fallback email address used by Maven. This should not be modified.

        "DefaultEmail": "sb.api@uaar.net",

        // CustomerName: Name that will appear in SupportBee tickets submitted to AgWare.

        "CustomerName": "",

        // CustomerEmail: Email address of the Customer that is used when submitting tickets

        //   to AgWare.

        "CustomerEmail": ""

      }

    },

    // Reports: Options for the Reports that are generated by Maven.

    "Reports": {

        // CustomTemplatePath: Absolute path to a directory containing .docx files to use as

        //   Custom Report Templates. If not set, Maven uses Tempates\Custom inside its own directory.

        //   Examples:

        //      \\\\SERVER-NAME\\Documents\\MavenTemplates

        //      D:\\Documents\\Reports\\MavenTemplates

        //   Note that `\` characters must be doubled-up to work.

        "CustomTemplatePath": ""

      },

    "AllowedHosts": "*"

  }