# 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 such as [Digitalocean](https://www.digitalocean.com/) or [Linode](https://www.linode.com/) 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 Any modern browser (not Internet Explorer) with Javascript enabled on any device with a minimum display width of 360 pixels. ## System requirements - OS : Linux x64 operating system [supported by ASP.NET Core](https://docs.microsoft.com/en-us/dotnet/core/install/linux) - 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 ## Installation procedure ### Swap space 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. DigitalOcean [has a guide](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-20-04) for Ubuntu droplets that walks through the process or see your distribution documentation for setting this. 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. ### Install ASP.NET Core runtime AyaNova requires the ASP.NET Core runtime version 6.0 or newer 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](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 so be sure to read through the instructions carefully. Confirm ASP.NET Core runtime is installed and available before proceeding to the next step: ```bash dotnet --list-runtimes ``` The AspNetCore runtime should be displayed with version 6 or newer: ``` Microsoft.AspNetCore.App 6.0.2 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App] Microsoft.NETCore.App 6.0.2 [/usr/share/dotnet/shared/Microsoft.NETCore.App] ``` If you do not see this go through the installation steps above again. ### 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/](https://www.postgresql.org/download/linux/) ### 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: ```bash sudo -u postgres psql ``` Set your desired password: ```bash 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. ### 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. ```bash 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 ``` ### Create folders for AyaNova AyaNova requires several folders to be created: the AyaNova binary and other server and web application files, AyaNova data and the .local-chromium folder to contain a local copy of the Chromium browser for report rendering. Create the AyaNova binary files folder. We recommend `/var/ayanova`: ```bash sudo mkdir /var/ayanova ``` Create the data folder. We recommend and AyaNova defaults to '/var/ayanova/data' in it's configuration: ```bash sudo mkdir /var/ayanova/data ``` Create the .local-chromium folder: ```bash sudo mkdir /var/ayanova/.local-chromium ``` ### Download the AyaNova binaries archive Switch to the AyaNova binary folder ```bash cd /var/ayanova ``` Download the AyaNova archive to the binary files folder created in the previous step. [https://www.ayanova.com/download/ayanova-linux-x64-server.zip](https://www.ayanova.com/download/ayanova-linux-x64-server.zip) Using curl utility: ```bash sudo curl -O https://www.ayanova.com/download/ayanova-linux-x64-server.zip ``` ### Unzip the archive Unzip the archive into the AyaNova server binary files folder created in the previous step: ```bash sudo unzip ayanova-linux-x64-server.zip ``` ### Server configuration The server **must** be configured before it will be able to start properly and find the database server. The AyaNova bin folder has a `config.json` file which is AyaNova's initial source for [configuration settings](ops-config-environment-variables.md) required for the server to start. It is necessary to edit this file (or provide an [alternative source of configuration](ops-config-environment-variables.md) and specify the password to connect to the PostgreSQL server. For example, if editing the default config.json file: ```json { "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](ops-config-db.md) 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](ops-config-use-urls.md) 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](ops-config-jwt-secret.md) 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. ```json { ...existing properties... "AYANOVA_LOG_LEVEL": "Info", "AYANOVA_JWT_SECRET": "1111111MyRandom32CharacterSecret" } ``` Edit the config.json file in your favorite editor, here we'll use Nano: ```bash sudo nano config.json ``` Make changes and save with `ctr-x` and type `y` to answer "Save modified buffer?" prompt. ### Set ownership and permissions AyaNova will be assumed for these instructions to run as `www-data`. Give www-data ownership of the ayanova folder: ```bash sudo chown -vR :www-data /var/ayanova ``` Set permissions to read / write for the AyaNova data folder: ```bash sudo chmod -R g+rw /var/ayanova/data ``` Set permissions to read / write / execute for the .local-chromium folder: ```bash sudo chmod -R g+rwx /var/ayanova/.local-chromium ``` ### 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: ```bash 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: ```bash sudo systemctl enable ayanova.service ``` ### Start and confirm AyaNova server Start the server service ```bash 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: ```bash 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](img/ops-install-linux-service-running.png) To exit the status display type `q` and enter to quit. ### Local network access 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 such as Digitalocean or Linode 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](https://letsencrypt.org/). 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](https://nginx.org/) 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. #### Install NGINX Install NGINX to be the reverse proxy server: ```bash 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: ```bash 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: ```bash sudo ufw app list ``` You should see NGINX listed in the available applications list. Enable NGINX under ufw: ```bash 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 / { 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; } 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 folder: ```bash cd /etc/nginx/sites-enabled ``` Make a backup copy of the existing `default` config file to your HOME folder just in case (note: you cannot backup to the same folder or NGINX will attempt to load it): ```bash cp /etc/nginx/sites-enabled/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: ```bash sudo nano default ``` delete all text and replace it with this text: ``` server { listen 80; #server_name ayanova.example.com www.ayanova.example.com; location / { 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; } } ``` 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: ```bash 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: ```bash sudo systemctl restart nginx ``` #### 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. 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. ### 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. ### SSL Certificate through Let's Encrypt Install the Let's Encrypt Certbot application and it's NGINX handler at the server: ```bash 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: ```bash sudo certbot --nginx -d ayanova.example.com -d www.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. The NGINX default config file will now have new entries looking something like this: ``` server { server_name ayanova.example.com www.ayanova.example.com; location / { 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; } listen 443 ssl; # managed by Certbot ssl_certificate /etc/letsencrypt/live/green.helloayanova.com/fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live/green.helloayanova.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 = green.helloayanova.com) { return 301 https://$host$request_uri; } # managed by Certbot listen 80; server_name ayanova.example.com www.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. #### Confirm AyaNova can be access 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. ### 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. ## Getting started and using AyaNova The next step is to [login](ay-start-login.md), request or install a [license](adm-license.md) and if are trying out AyaNova for the first time follow the [evaluation trial guide](ay-evaluate.md). We also recommend looking over the [operations maintenance](ops-maintenance.md) guide to ensure AyaNova runs smoothly and data is safe and secure.