AyaNova installation - Windows IIS hosted

Please read through all the instructions below before proceeding with installation to be sure everything is available and ready.

There are several steps that need to be done as documented here or AyaNova will fail to work properly.

These instructions require a working knowledge of Windows server adminstration tasks.

This installer includes the AyaNova server application only and depends on an IIS server, a PostgreSQL server be installed or accessible and the .net Core framework to be installed in the correct order (detailed below).

This type of installation is suitable for both outside internet access and inside the local network.

No installation is required at the user end to access the AyaNova web app with a supported browser.

AyaNova web app system requirements

An up to date modern web browser (not Internet Explorer) with Javascript enabled on any device with a minimum display width of 360 pixels. While other browsers may work, we test AyaNova on the most recent two releases of Chrome, FireFox, Safari and Edge on Windows, Android and Apple platforms.

AyaNova server system requirements

• OS : Windows 64 bit operating system with IIS
• IIS: Internet information server
• Internet connection : required to install license and to automatically download the Chromium report rendering engine
• Disk space: minimum 2GB of free disk space
• RAM : 1GB (minimum), 2+ GB (recommended)
• Static IP address if AyaNova will be used from the internet
• Domain or subdomain name if AyaNova will be used from the internet

Security and Network requirements to access IIS from the internet

In order to access the AyaNova server through IIS from the internet a static IP address is required, optionally a registered domain name as well as appropriate configuration of IIS and the router to allow secure, incoming connections to the IIS server from the internet.

The following instructions are provided to get IIS running with AyaNova inside your network so it's ready for the next steps of exposing it to the outside world which will require a domain name, DNS configuration as well as site and equipment specific configuration best done by an experienced network professional and are beyond the scope of this manual or the support we can provide.

If a networking technician has a question about AyaNova itself that is not answered in this manual contact us: support@ayanova.com.

Folders

• Program files : By default (and recommended) AyaNova server program files will be installed to C:\Program Files\ayanova folder
• Data files: All data aside from attachment files is stored in the PostgreSQL database. By default AyaNova will store attachment files, logs and backup files in the %ProgramData% folder under ayanova which on most computers will be located at C:\ProgramData\ayanova. Each folder location can be changed via configuration.

Installation procedure

Follow the steps below in the order they are presented here.

1. Enable IIS Internet Information Server

If you already have IIS enabled read through and verify the following instructions to verify it is ready for AyaNova.

The steps to enable IIS are different depending on the type of Windows in use, for server Windows systems use the next section, for non server versions of Windows skip to the next section below.

Enable IIS on server Windows versions

The following images are taken from a Windows Server 2019 operating system but the procedure is very similar for any modern version of Windows server.

Use the Add Roles and Features wizard from the Manage menu or the link in Server Manager, check the box for Web Server (IIS):

If IIS is being enabled for the first time you can accept all remaining defaults to conclusion.

If IIS was already enabled, double check the default settings for Role Services for IIS are enabled:

Reboot is not required at this point, continue on to the PostgreSQL installation below.

Enable IIS on non-server Windows versions

Open the Apps & Features settings page from the Apps shortcut in Settings:

In Apps & Features select the "Programs and Features" link under "Related settings" in the upper right corner of the Apps & Features page:

In "Programs and Features" dialog box select "Turn Windows features on or off" link:

Select the IIS Feature:

If IIS is being enabled for the first time you can accept the defaults. If IIS was already enabled, double check the defaults for IIS are enabled.

Select the OK button and Windows will enable IIS. Reboot is not required at this point, continue on to the PostgreSQL installation below.

2. Install PostgreSQL server

AyaNova requires access to a PostgreSQL database server version 12 or newer. It should be up and running before AyaNova is installed. If you do not have a PostgreSQL server already then it must be installed to a location visible to the AyaNova server (same computer or a local computer on the same network). PostgreSQL is open source and free to use.

If you need to install PostgreSQL follow this installation guide https://www.postgresqltutorial.com/install-postgresql/

Note: we have seen cases during testing where the PostgreSQL installer will show error messages related to Visual C++ runtime file installation on the latest Windows server platforms however this appears to be cosmetic only and doesn't affect operation of PostgreSQL.

PostgreSQL server password

If you are installing PostgreSQL you will be prompted to provide a password to access it. Be sure to make a note of this password as AyaNova will need it to be specified later in the AYANOVA_DB_CONNECTION configuration setting after installing the AyaNova server.

Warning: Be careful about using special characters for your Postgres connection string, particularly the password and database name, we've encountered issues with the automatic internal backup failing due to a @ or $ symbol in the password. On some platforms when AyaNova attempts to run the backup utility it may fail if that operating system does not support certain special characters found in the password as they may interfere with the "shell" command called to perform the backup.

3. ASP.NET Core Runtime

IMPORTANT: IIS MUST be installed before the ASP.NET Core runtime. AyaNova will not work if IIS is installed after the ASP.NET Core runtime.

If IIS is not already enabled and running do not proceed until it is.

The ASP.NET Core runtime will see IIS and install appropriate components but only if IIS is present during the ASP.NET Core runtime installation.

AyaNova is built upon the ASP.NET Core runtime version 8.x.x and it should be present before AyaNova is installed.

Warning Microsoft provides several different links to "asp.net core runtime" downloads; the one required by AyaNova is the link labelled "Hosting bundle" and it is in the runtimes section under Windows.

Download the ASP.NET Core Hosting bundle runtime here https://dotnet.microsoft.com/en-us/download/dotnet/8.0.

Run the installer and take the defaults.

Confirm your ASP.NET Core runtime is installed and running by opening a DOS command / Windows Shell window and typing

dotnet --list-runtimes

The AspNetCore runtime should be displayed with version 8.x.x, for example:

Microsoft.AspNetCore.App 8.0.5 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 8.0.5 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

(your version may be newer)

4. AyaNova server installation

Once you have ensured the three requirements above are installed and available, download and run the AyaNova network installer: https://www.ayanova.com/download/ayanova-windows-x64-lan-setup.exe.

Smart screen warning

You may receive a "Smart Screen" warning from Windows such as the following:

Clicking on More info will reveal the following:

Use the Run anyway button to start the installation.

Why is the installer blocked by SmartScreen?

Windows SmartScreen blocks all files that it does not know. When a new version is released, these files are unknown to SmartScreen and thus SmartScreen warns about them.

As more and more users install the new version, SmartScreen learns that the files are good. As soon as enough users have installed the new version, SmartScreen does not warn about it anymore.

SmartScreen does not support allowing software developers to request adding to a 'whitelist' when a new version of their software is published.

IMPORTANT: You MUST UNCHECK the option 'Start AyaNova server when Windows starts'

This is because IIS will be responsible for starting and stopping AyaNova. If you accidentally select start with windows re-run the installer and uncheck it and finish the installation again.

Click next to continue to the next step:

You will be prompted to go to the asp.net core download page:

If you have already downloaded and installed ASP.NET Core Runtime, select No. Otherwise select Yes, and complete that installation before proceeding.

You will next be prompted to go the PostgreSQL installer page:

If you have already downloaded and installed PostgresSQL database server, select No. Otherwise select Yes, and complete that installation before proceeding.

Finish the installation.

Do not run any component yet, further configuration is needed.

5. AyaNova Server configuration

The AyaNova server must be configured before it will be able to start properly and find the Postgres database server.

Configuration is done by editing the config.json file that has been installed to the c:\Program Files\ayanova\ folder.

Run NotePad as Administrator to be able to edit and save in the program files folder by right clicking on the Notepad icon in the start menu, select More and Run as administrator:

From in Notepad, open the config.json file located in the location the AyaNova server had been installed to - default location is c:\Program Files\ayanova\

The default installed config.json file will initially have the following:

{
  "AYANOVA_USE_URLS": "http://*:7575",
  "AYANOVA_DB_CONNECTION": "Server=localhost;Username=postgres;Password=YOUR_PASSWORD_HERE;Database=AyaNova;",
  "AYANOVA_DEFAULT_TRANSLATION": "en",
  "AYANOVA_BACKUP_PG_DUMP_PATH": "C:\\Program Files\\PostgreSQL\\16\\bin",
  "AYANOVA_DATA_PATH": "%ProgramData%\\ayanova",
  "AYANOVA_LOG_LEVEL": "Info"
}

Note that any back slashes need to be doubled in config.json file or the server will fail to start.

Do not edit properties unless specifically indicated. If you encounter an issue, reconfirm your edits.

DO NOT EDIT:

The AYANOVA_USE_URLS property specifies which TCP / IP Port that AyaNova server should listen on for connections from web browsers. The default value is port 7575 which should be free in most cases, however if you need to use an alternate port due to conflict it must be set here. We recommend using the default 7575 to avoid current or future confusion or conflict with other servers that may be installed or present elsewhere on the network.

The USE URLS setting affects the address users will use to connect to the AyaNova server in their web browser. For example, to access the AyaNova server from the same computer the server is running on with the default port 7575 you would use this link in your browser http://localhost:7575, however from another computer on the network you would access the server via it's IP address, so, for example if the AyaNova Server computer's IP Address on your network was 192.168.1.10 users on another computer might connect via this address http://192.168.1.10:7575.

EDIT NEEDED:

The AYANOVA_DB_CONNECTION property must be edited and where it has "YOUR_PASSWORD_HERE" substitute the actual PostgreSQL password to be used that was previously set. If the database server is located on a different computer then the Server= connection string property must be set to the address of that computer.

EDIT ONLY IF NEEDED:

The AYANOVA_BACKUP_PG_DUMP_PATH property specifies the path to the PostgreSQL database backup utility pg_dump if AyaNova server will be doing the automatic daily backups.

A. if AyaNova server will be doing the automatic daily backups using AyaNova's Backup feature, confirm this path stated matches the path to YOUR PostgreSQL database backup utility pg_dump B. otherwise, If you already have a backup solution in place for your PostgreSQL databases AND WILL NOT BE USING AYANOVA'S Backup feature, remove this

OPTIONAL EDIT:

Modify the 32 character AYANOVA_JWT_SECRET property of the configuration which ensures that the logged in User's session can survive a restart of the AyaNova server. If this is not set AyaNova will invalidate all login tokens any time the server restarts by generating a new random JWT secret on boot which under IIS happens frequently.

Change this from the default of "11111YourRandom32CharacterSecret" to be unique to your site (must be 32 characters).

{
  ...existing properties...
  "AYANOVA_LOG_LEVEL": "Info",
  "AYANOVA_JWT_SECRET": "11111YourRandom32CharacterSecret"
}

After editing, saving and exiting out of NotePad, open the config.json file AGAIN to confirm that the changes were saved correctly and that the file is still specifically labeled with the name and extension config.json

6. Boot and test the server

AyaNova must be confirmed to run properly BEFORE the final configuration in IIS to host AyaNova. Do so by following this boot and test.

The AyaNova installer will have created two shortcuts in the Start Menu under "AyaNova Server"

The AyaNova installer also creates two shortcuts on the Windows desktop titled "AyaNova server" and "AyaNova App".

6.1 Double click the AyaNova Server shortcut

The AyaNova Server shortcut will start a local copy of PostgreSQL, then AyaNova by running AyaNova.exe in the program files folder where AyaNova was installed.

You should see a console window open and some text that indicates the server version and that it is booting. Any problems found that prevent boot up will be displayed here. If all is well then the console window will display "BOOT: COMPLETED - SERVER OPEN" as well as some other configuration data.

If the server closes immediately upon running with an error

In some cases where there is a critical error completely preventing AyaNova server from running, the server console may display the error but close too quickly to read it. In this case you can view the message by opening a shell / command line prompt and starting AyaNova.exe manually from it's program files ayanova folder.

If you see an error about the config.json file there is likely a comma missing or some other format issue from when it was edited in the earlier step. Double check that it's not missing a comma or has an extra comma at the end that is not required or anything else that stands out.

If you receive an error that mentions Microsoft.NETCore.App it may be that the .net installation did not complete properly even though the display runtimes command executed properly. In this case the issue is often resolved by redoing the .net installation instructions above.

6.2 Double-click the AyaNova App shortcut

The AyaNova App shortcut will start a batch file which in turn will open the default browser to the AyaNova server's landing page at the default address.

Note that the AyaNova Server and the AyaNova App shortcut are ONLY relevant to this INITIAL configuration boot and test. Once AyaNova is confirmed to be working via IIS you will no longer access either of these desktop shortcuts. Do KEEP for diagnostic purposes only, you may want to relabel as "Diagnosic AyaNova Server" and "Diagnostic AyaNova App".

Only after you have confirmed that AyaNova server is working and you can login to the AyaNova web app should you proceed to the next step of enabling IIS to work with AyaNova.

7. IIS AyaNova site configuration

Now that AyaNova server has been confirmed to boot properly IIS needs to be set up to host the AyaNova server.

7.1 Stop AyaNova server if still running

If your AyaNova server is still running from the previous "Boot and test the AyaNova Server", stop the AyaNova Server by pressing the ctrl-c key combination as stated in the launcher window. The window will close when you press ctrl-c in the launcher window.

From this point on IIS will be controlling the starting and stopping of the AyaNova server.

7.2 Open IIS manager

From a server version of Windows...

Click on Tools -> Manage menu item from server manager:

From a non-server version of Windows...

Access IIS manager from the Windows Start menu in the Windows Administrative Tools start menu folder:

7.3 Create the AyaNova IIS site

In the Connections panel open the server's node, right click on Sites to add a new site.

In the Add Website dialog box configure the website settings, the Site Name, Physical Path and Port are the only required settings to be changed.

Here is an example configuration that is suitable to allow internal users to access AyaNova over port 8080 via HTTP (not https) and is suitable to test AyaNova internally but is not suitable for outside access:

Note that the Site name was set to "AyaNova", the physical path is set to the program files folder where AyaNova.exe resides after installation, the image shows the default location.

The Port setting here has been set to 8080 which is intended to not conflict with a default website that comes with IIS which is already on port 80 the web browser http default port. Do not choose the same port number as AyaNova (by default 7575), that port must be left free for AyaNova to use to communicate with IIS.

Click on OK to save the settings and procede to the next step.

7.4 Edit Application Pool

Three settings must be changed in the Application Pool for AyaNova to work properly.

Under the Server's node in the Connections panel select "Application Pools" then right click the AyaNova site application pool which will have the same name as the Site name configured in the previous step ("AyaNova") to open the application pool context menu.

Select "Advanced settings" from the context menu:

Adjust CLR Version

In the application pool dialog "(General)" section set the .NET CLR version to "No Managed Code":

This may seem counterintuitive since AyaNova uses .NET but AyaNova uses .NET Core, which is not the same .NET referred to here.

Adjust Idle timeout

In the application pool dialog "Process Model" section the Idle timeout setting must be set to zero to prevent IIS from shutting down AyaNova when usage is low which would prevent AyaNova from processing background tasks like the daily backup or generating Workorders from PM's etc.

The default is 20 minutes but we need it to be set to 0 to completely turn off idle timeouts:

Adjust recycle

In the application pool dialog "Recycling" section there are two settings that must be configured to prevent AyaNova from being restarted when it's actively processing a backup job or generally busy with Users.

It's a good idea to allow IIS to recycle periodically however, by default it will do it every 1740 minutes which eventually will conflict with AyaNova's scheduled daily backup job or at a time when usage is high during the day so we need to turn that off and instead set it to recycle at a specific time of day that will not conflict with the daily backup or a busy time for AyaNova usage.

For the purposes of this document we'll assume the AyaNova server is not in peak demand overnight and the backup will be configured for 11:59pm making 3am a good time to recycle, however you should adjust this based on your specific site needs.

There are two settings to configure in the "Recycling" section of the Application Pool settings.

First we need to turn off the "Regular time interval" 1740 minute recycle by setting it to 0:

Next we need to add a "Specific Time", the entry box is in 24 hour time format so we will enter 03:00:00 for 3am:

Typically 3am is a good time as the backup in our scenario starts at 11:59pm and should be completed by 3am and users won't be accessing the server at 3am however you must adjust this time to be appropriate for your site specific needs. The AyaNova server should completely restart in less than a minute but it will affect the backup if it was in progress and potentially interfere with active users.

Save the recycle time once entered and click on Ok to save and continue to the next step.

8. Open AyaNova app through IIS

Right click on the AyaNova site created earlier in IIS Manager and select "Manage website" and then "Browse". The AyaNova web app should open to the login (or license agreement) page.

If you receive an error message from IIS "HTTP Error 500.19 - Internal Server Error The requested page cannot be accessed because the related configuration data for the page is invalid." This generally means you did not follow the steps in the correct order and ASP.NET Core was installed before IIS was enabled which means IIS doesn't have the proper handlers to run an ASP.NET Core application. In order to fix this run the ASP.NET Core hosting bundle setup again that was installed previously (repair installation) to ensure IIS is setup with the correct handlers.

9. Starting and stopping AyaNova server

Going forward, IIS will automatically manage starting and stopping AyaNova as required.

10. Next steps

Server installation under IIS for internal access is complete. Users will require the URL to use in their browser to access the AyaNova APP that was opened in the last step to test AyaNova substituting the server's IP address for the "localhost" part of the URL.

For connection from the internet your network adminstrator will need to setup IIS with an SSL certificate, bind to the correct port and domain name and open the port on the router to allow outside connections and finally provide your users with the correct URL to access AyaNova from outside your network.

AyaNova can only be securely accessed from the internet if it's secured with an SSL certificate and only allows an HTTPS connection and not an unsecured HTTP connection.

Let's Encrypt provides free SSL certificates and lists several Windows clients for use with Let's Encrypt on Windows.

Report rendering first time delay

The very first time a report is rendered in AyaNova there will be a delay while the Chromium browser report rendering components are installed.

Report rendering error

In some cases there may be a futher setting required for report rendering.

If you render a report and see this error:

JobFailed: PuppeteerSharp -> Evaluation failed: TypeError: Failed to fetch at ayPostToAPI

You will need to set the AYANOVA_REPORT_RENDER_API_URL_OVERRIDE setting in the AyaNova server configuration to your AyaNova server's external URL address to enable report rendering for your configuration.

Getting started and using AyaNova

The next step is to login, request or install a license and if are trying out AyaNova for the first time follow the evaluation trial guide.

To ensure AyaNova runs smoothly and data is safe and secure be sure to look over the Server operations configuration and maintenance guide.

For Business administration and setting things up from a business perspective, review the Getting started - Set up for production use step in our Getting started guided tour.