Skip to content

AyaNova installation - linux server

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

These instructions assume shell access to a Linux server and a working knowledge of Linux adminstration tasks.

We also offer installation services, contact AyaNova support for details and pricing.

The "SERVER" installation configuration is appropriate for use both within a private office network or from the internet.

Once the AyaNova server is up and running users can access it with their web browsers pointed to the address of the AyaNova server.

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

Linux distributions

These instructions were compiled and tested on an Ubuntu 20 server OS however any Linux x64 distribution should work provided the ASP.NET Core framework can be installed to it.

Hosted linux

There is no significant difference in setup between a linux server physically on premise or hosted from a hosting provider with SSH shell access.

The largest demand put on an AyaNova server is report rendering so if it will be common to render reports with dozens or hundreds of pages you will find that more memory and CPUs will be beneficial.

However a small shop that renders smaller page count reports can often be served with a 2GB memory single CPU virtual server. Since it's easy to scale up a virtual server we recommend starting with the minimum requirements and scaling up as necessary.

The hosting providers CPU and memory monitoring tools will be helpful here to determine if more resources are required.

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.

System requirements

  • OS : Linux x64 operating system supported by ASP.NET Core
  • 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)
  • Sufficient swap space if a low memory server is used ( < 4gb)
  • Modern web browser with Javascript enabled
  • Static IP address if AyaNova will be used from the internet
  • Domain or subdomain name if AyaNova will be used from the internet
  • Curl package installed (sudo apt install curl)
  • Unzip package installed (sudo apt-get install zip unzip)

Installation procedure

1. Swap space configuration

If your server has 2 GB of RAM or less or will be rendering many reports simultaneously it's important to set a swap file to ensure your server doesn't completely run out of memory during report rendering. Report rendering is memory intensive and it's easily possible to completely run out of memory, particularly on a 2GB or less RAM scenario with no swap space available which can crash the server or render it completely unresponsive.

Swap memory should be considered a stopgap emergency measure only and not relied upon regularly to ensure sufficient memory. If the swap file is being accessed regularly it's a clear indication that more ram needs to be installed or allocated.

We recommend double the size of ram allocated to swap space so if you have 1GB of ram then a 2GB swap space is appropriate.

2. Install ASP.NET Core runtime

AyaNova requires the ASP.NET Core runtime version 6.x and Microsoft provides a step by step guide to install it properly on each version of Linux.

Install the "ASP.NET CORE RUNTIME" (NOT SDK VERSION) using this guide for your specific OS https://docs.microsoft.com/en-us/dotnet/core/install/linux

There are three different versions of .net core listed, be sure you select the "ASP.NET Core Runtime" version.

There are different procedures for different versions of Linux and there is a step before the actual installation to add the microsoft package repository so be sure to read through the instructions carefully.

Confirm ASP.NET Core runtime is installed and available before proceeding to the next step:

dotnet --list-runtimes

The AspNetCore runtime should be displayed with version 6.x:

Microsoft.AspNetCore.App 6.0.3 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 6.0.3 [/usr/share/dotnet/shared/Microsoft.NETCore.App]

If you do not see this go through the installation steps above again.

3. Install PostgreSQL server

AyaNova requires access to a PostgreSQL database server version 12 or newer. If you do not have a PostgreSQL server already available then it must be installed to a location visible to the AyaNova server (same computer or a local computer on the same network).

We recommend not using the version of PostgreSQL provided by your OS package manager as they tend to be out of date.

To install PostgreSQL directly start here https://www.postgresql.org/download/linux/

4. Set the PostgreSQL password

If you are installing a local copy of PostgreSQL for the first time to use with AyaNova a password will need to be set for secure access. PostgreSQL on linux defaults to no password and must be secured. If you have an existing PostgreSQL server then you can skip this step but will need a PostgreSQL server password in a later step.

Open a PostgreSQL psql console as the postgres user:

sudo -u postgres psql

Set your desired password:

ALTER USER postgres PASSWORD 'YOUR_PASSWORD_HERE';

If successful psql will display "ALTER ROLE" in response and you can close the psql console by typing \q to quit.

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.

5. Install Chromium browser support libraries

AyaNova uses a "headless" Chromium browser to render report templates. Server versions of Linux do not have the required support libraries for Chromium to render reports so they must be installed in advance.

sudo apt-get install -yq gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 \
libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 \
libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 libgbm1 \
ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget

6. Create directories for AyaNova

AyaNova requires several directories to be created: the AyaNova binary and other server and web application files, AyaNova data and the .local-chromium directory to contain a local copy of the Chromium browser for report rendering.

Create the AyaNova binary files directory. We recommend /var/ayanova:

sudo mkdir /var/ayanova

Create the data directory. We recommend and AyaNova defaults to '/var/ayanova/data' in it's configuration:

sudo mkdir /var/ayanova/data

Create the .local-chromium directory:

sudo mkdir /var/ayanova/.local-chromium

7. Download and unzip the AyaNova binaries archive

The following shell script will automatically download and unzip the latest AyaNova server files.

You must have the Curl and Unzip utilities installed before running this command.

From a terminal window run the following commands:

cd /var/ayanova && \
sudo curl -O https://www.ayanova.com/download/ayanova-linux-x64-server.zip && \
sudo unzip -o ayanova-linux-x64-server.zip

If there is an issue or error break apart the commands and execute each one individually to find the error.

8. Server configuration

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

The AyaNova bin directory has a config.json file which is AyaNova's initial source for configuration settings required for the server to start. It is necessary to edit this file (or provide an alternative source of configuration and specify the password to connect to the PostgreSQL server. For example, if editing the default config.json file:

{
  "AYANOVA_USE_URLS": "http://*:7575",
  "AYANOVA_DB_CONNECTION": "Server=localhost;Username=postgres;Password=YOUR_PASSWORD_HERE;Database=AyaNova;",
  "AYANOVA_DEFAULT_TRANSLATION": "en",
  "AYANOVA_DATA_PATH": "/var/ayanova/data/",
  "AYANOVA_LOG_LEVEL": "Info"
}

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.

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.

Optional but recommended: Add a 32 character AYANOVA_JWT_SECRET property to the configuration if you want to ensure that 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.

{
  ...existing properties...
  "AYANOVA_LOG_LEVEL": "Info",
  "AYANOVA_JWT_SECRET": "1111111MyRandom32CharacterSecret"
}

Edit the config.json file in your favorite editor, here we'll use Nano:

sudo nano config.json

Make changes and save with ctr-x and type y to answer "Save modified buffer?" prompt.

9. Set ownership and permissions

AyaNova will be assumed for these instructions to run as www-data.

Give www-data ownership of the ayanova directory:

sudo chown -vR :www-data /var/ayanova

Set permissions to read / write for the AyaNova data directory:

sudo chmod -R g+rw /var/ayanova/data

Set permissions to read / write / execute for the .local-chromium directory:

sudo chmod -R g+rwx /var/ayanova/.local-chromium

10. Create and install a service to run AyaNova automatically

As AyaNova is a server application running on a server operating system it needs to start automatically when the Linux server boots and restart automatically in the (unlikely) event that it crashes.

Create the ayanova.service file:

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

Paste or re-create the following contents of the service file (edit as necessary if not using defaults):

[Unit]
Description=AyaNova server

[Service]
WorkingDirectory=/var/ayanova
ExecStart=/usr/bin/dotnet /var/ayanova/AyaNova.dll
Restart=always
# Restart service after 10 seconds if it crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=ayanova-server
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

Make the changes and save with ctr-x and type y to answer "Save modified buffer?" prompt.

Enable the service:

sudo systemctl enable ayanova.service

11. Start and confirm AyaNova server

Start the server service

sudo systemctl start ayanova.service

Confirm the AyaNova service is running by first waiting for about 20 seconds after the last step for AyaNova to boot up then viewing the service status:

sudo systemctl status ayanova.service

You should see in the service status display the AyaNova server version and that it is booting. Any problems found that prevent boot up will be displayed here.

Note that the first boot of AyaNova may require a few seconds to fully open before you will see server open message below. If you view the status too soon you may not see it get to BOOT: COMPLETED yet. In that case type q to quit and then show status again.

If all is well the status will display "BOOT: COMPLETED - SERVER OPEN" as well as some other configuration data:

AyaNova service running

To exit the status display type q and enter to quit.

Local network access only

If users are accessing AyaNova only on a private local area network no more installation steps are required and AyaNova should be ready for use. Assuming the default port of 7575 is in use then the URL would be similar to:

http://YOUR_LOCAL_NETWORK_AYANOVA_SERVER_IP_ADDRESS:7575

If users will need to access AyaNova from the internet continue to the next step Internet access otherwise you can skip it and move on to Getting started and using AyaNova below.

Internet access

If users will be accessing AyaNova from the internet a few extra requirements are necessary to ensure security. The following items will be required to configure AyaNova on a linux server for internet access:

Static IP address

A static IP address is required to host AyaNova on the internet. If you have a virtual or physical server through a server hosting provider then you will already have a static IP address. If you are hosting your own server on premise on a private office network connecting to the internet via an Internet Service Provider you will need to ensure your ISP has provided you with a static IP address and if they haven't you will need to request a static IP address and have that address on hand before proceeding.

Registered domain name

An internet domain name is required to get an SSL certificate for secure encrypted communications between the AyaNova server and the end user across the internet. An entry will need to be made in your DNS record for your domain to provide a name to access the AyaNova server and it must point to the static IP address of your router or server. If the only service on your domain will be AyaNova then you can use the root domain name i.e. example.com or www.example.com but it's more common to use a subdomain specifically for AyaNova, i.e. ayanova.example.com.

This DNS record needs to be in place and active before proceeding and can take minutes to hours to propagate so be sure to do this as soon as possible.

SSL certificate

These instructions will assume use of a free SSL certificate from LetsEncrypt. If you already have an SSL certificate adapt these instructions to match your situation.

Reverse proxy server

We will provide instructions for using the free and open source NGINX as a reverse proxy server, if you already have another server capable of being a reverse proxy (such as Apache) you will need to adapt these instructions to match your situation.

A. Install NGINX

Install NGINX to be the reverse proxy server:

sudo apt install nginx

The server's firewall may need to be adjusted. Firewall configuration is beyond the scope of this installation guide, be sure you have a firewall in place and set correctly, we will outline the requirements as they relate to AyaNova itself.

Port 80 http will need to be open for requesting SSL certificates from LetsEncrypt and port 443 https will need to be open for ongoing access.

AyaNova itself does not require any port to be open to the outside world other than HTTPS port 443 for the reverse proxy server.

For hosted linux through a cloud provider the firewall may be set in the cloud networking control panel and there then would be no firewall required at the server itself and you can skip this step, otherwise ufw is commonly used.

NGINX registers itself as a service with ufw on installation so if ufw is active on your server it can be adjusted to work with NGINX as follows:

First confirm ufw is active:

sudo ufw status

If the response is status: inactive then there is no need to configure ufw further however be sure you have a firewall of some kind in place.

If ufw is active confirm it knows about NGINX:

sudo ufw app list

You should see NGINX listed in the available applications list.

Enable NGINX under ufw:

sudo ufw allow 'Nginx Full'
Configure NGINX site for AyaNova

NGINX needs to be configured to reverse proxy to AyaNova server.

If you are already using NGINX then examine the following and adapt it to your existing configuration, if you have no existing NGINX services skip to the next section to create one for AyaNova.

Existing NGINX services

If you are already using NGINX for other services then a site configuration file entry will need to be made to reverse proxy AyaNova with appropriate settings for your site. We cannot provide details for that as it must work with your existing NGINX configuration, however here is an example of the AyaNova specific parts only taken from a working site that uses Let's Encrypt certificates to give an idea of what is required:

server {
        server_name   ayanova.example.com www.ayanova.example.com;
    location / {
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
        add_header X-XSS-Protection "1; mode=block" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header Referrer-Policy "strict-origin" always;
        gzip on;
        gzip_vary on;
        gzip_min_length 10240;
        gzip_proxied expired no-cache no-store private auth;
        gzip_http_version 1.1;
        gzip_types  application/javascript text/css application/json text/plain;


        proxy_pass         http://127.0.0.1:7575;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_connect_timeout       3600;
        proxy_send_timeout          3600;
        proxy_read_timeout          3600;
        send_timeout                3600; 
        # Note: the client_max_body_size setting controls the maximum upload size for attachments in AyaNova
        # it is a good security precaution to set this value only as high as absolutely needed by your staff for
        # file attachment uploads
        # AyaNova can handle up to 10GB maximum so the highest setting allowed here would be:
        # client_max_body_size 10GB;
        client_max_body_size 25M;
    }

    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/ayanova.example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/ayanova.example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
Completely new NGINX service for AyaNova only

If this is a new install dedicated to AyaNova only and no existing NGINX services or websites will be impacted then replace the default NGINX configuration file as follows:

Switch to the NGINX configuration directory:

cd /etc/nginx/sites-available

Make a backup copy of the existing default config file to your HOME directory just in case:

cp /etc/nginx/sites-available/default ~/nginx-default-backup

Open the existing default config file in an editor, replace it's contents entirely with the following configuration and save:

If using Nano text editor:

sudo nano default

delete all text and replace it with this text:

server {
    listen        80;
    #server_name   ayanova.example.com;
    location / {
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
        add_header X-XSS-Protection "1; mode=block" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header Referrer-Policy "strict-origin" always;
        gzip on;
        gzip_vary on;
        gzip_min_length 10240;
        gzip_proxied expired no-cache no-store private auth;
        gzip_http_version 1.1;
        gzip_types  application/javascript text/css application/json text/plain;

        proxy_pass         http://127.0.0.1:7575;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_connect_timeout       3600;
        proxy_send_timeout          3600;
        proxy_read_timeout          3600;
        send_timeout                3600; 
        # Note: the client_max_body_size setting controls the maximum upload size for attachments in AyaNova
        # it is a good security precaution to set this value only as high as absolutely needed by your staff for
        # file attachment uploads
        # AyaNova can handle up to 10GB maximum so the highest setting allowed here would be:
        # client_max_body_size 10GB;
        client_max_body_size 25M;
    }
}

Note that the server name is intentionally commented out with a # symbol for now. In a later step you will uncomment it and replace the example domain with the one registered previously.

In a later step the Let's Encrypt Certbot will automatically update this file with the correct settings for ongoing use, this is only the initial configuration to allow Let's Encrypt access.

Confirm that NGINX sees the configuration as valid:

sudo nginx -t

You should see a response similar to this:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart NGINX so the new configuration takes effect:

sudo systemctl restart nginx

B. Confirm DNS has propagated

Confirm that you can now navigate to AyaNova web app login page through un-encrypted HTTP via the domain name configured earlier. i.e. http://ayanova.yourdomain.com or http://yourdomain.com if not using a subdomain.

Once DNS has propagated and you see the AyaNova web app login page (or license agreement page) over unecrypted HTTP it's time for the next step.

NOTE: In some cases the browser may not allow you to open an unecrypted HTTP site and will keep attempting to open with HTTPS instead, if this is the case and you don't receive an error about the domain being unknown then it's probably safe to just skip to the next step.

If DNS has propogated but you see an NGINX error page instead, confirm that AyaNova server is up and running and re-check the NGINX configuration.

C. Add domain name to NGNIX config

Open the NGINX config file previously modified again in your editor, remove the # symbol that is commenting out the server_name line and replace the server name example.com with your domain and or subdomain names previously registered, save and exit.

D. SSL Certificate through Let's Encrypt

Install the Let's Encrypt Certbot application and it's NGINX handler at the server:

sudo apt install certbot python3-certbot-nginx

Request a certificate from Let's Encrypt for the domain or subdomains previously registered and set in the NGINX config file:

sudo certbot --nginx -d ayanova.example.com

(Each separate server name and dns record can be appended to the command line with -d [YOUR_DOMAIN])

Accept the prompts choose the option to redirect to https. Certbot will re-write the default config file to properly include the https ports and SSL certificates.

If you get the following error you may have forgot to add the domain name to NGINX config:

Could not automatically find a matching server block for ayanova.example.com. Set the `server_name` directive to use the Nginx installer.

The NGINX default config file will now have new entries looking something like this:

server {
        server_name   ayanova.example.com;
    location / {
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
        add_header X-XSS-Protection "1; mode=block" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header Referrer-Policy "strict-origin" always;
        gzip on;
        gzip_vary on;
        gzip_min_length 10240;
        gzip_proxied expired no-cache no-store private auth;
        gzip_http_version 1.1;
        gzip_types  application/javascript text/css application/json text/plain;

        proxy_pass         http://127.0.0.1:7575;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_connect_timeout       3600;
        proxy_send_timeout          3600;
        proxy_read_timeout          3600;
        send_timeout                3600; 
        # Note: the client_max_body_size setting controls the maximum upload size for attachments in AyaNova
        # it is a good security precaution to set this value only as high as absolutely needed by your staff for
        # file attachment uploads
        # AyaNova can handle up to 10GB maximum so the highest setting allowed here would be:
        # client_max_body_size 10GB;
        client_max_body_size 25M;
    }

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/ayanova.example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/ayanova.example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
server {
    if ($host = ayanova.example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen        80;

    server_name   ayanova.example.com;
    return 404; # managed by Certbot


}

Certbot will also install a systemd timer event which will auto-renew the SSL certificate if it is within 30 days of expiration. Certificates are valid for 90 days currently with Let's Ecrypt.

E. Confirm AyaNova can be accessed securely

Confirm that you can now navigate to AyaNova web app login page through encrypted HTTPS via the domain name configured earlier. i.e. https://ayanova.yourdomain.com or https://yourdomain.com if not using a subdomain.

You should now see the login (or license agreement) page through an encrypted SSL connection and AyaNova is ready for use.

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.

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.