raven/docs/8.0/ayanova/docs/ops-install-linux-server.md

# 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 "Turnkey" solutions for AyaNova hosting, see our website at [AyaNova.com](https://ayanova.com) for details.

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 shell root access.

## 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 400mb of free disk space
- RAM : 512 MB (minimum), 1 GB (recommended)
- 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

### Install ASP.NET Core runtime

AyaNova requires the ASP.NET Core runtime version 6.0 or newer.
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.

NOTE: In the example command lines in the linked pages above they are sometimes missing the `sudo` command, be sure to add it before commands listed there if non root user.

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.0 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 6.0.0 [/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 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

}
```

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:

```
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 regular 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 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 page through an encrypted SSL connection and AyaNova is ready for use.

## Getting started and using AyaNova

The next step is to follow the [getting started](adm-getting-started.md) guide for using and administrating AyaNova from a business point of view and also the [operations maintenance](ops-maintenance.md) guide to ensure AyaNova runs smoothly and data is safe and secure.