This commit is contained in:
203
docs/8.0/ayanova/docs/ops-install-windows-iis.md
Normal file
203
docs/8.0/ayanova/docs/ops-install-windows-iis.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# AYANOVA HOSTED VIA IIS INSTALL GUIDE
|
||||
|
||||
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
|
||||
|
||||
Any modern browser (not Internet Explorer) with Javascript enabled on any device with a minimum display width of 360 pixels.
|
||||
|
||||
## 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 on installation
|
||||
- Disk space: minimum 400mb of free disk space
|
||||
- RAM : 512 MB (minimum), 1 GB (recommended)
|
||||
- PostgreSQL Server: installation guide [https://www.postgresqltutorial.com/install-postgresql/](https://www.postgresqltutorial.com/install-postgresql/)
|
||||
- ASP.NET Core Runtime Hosting bundle v6.0.0 or newer : Download [https://dotnet.microsoft.com/permalink/dotnetcore-current-windows-runtime-bundle-installer](https://dotnet.microsoft.com/permalink/dotnetcore-current-windows-runtime-bundle-installer)
|
||||
|
||||
## 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 anywhere.
|
||||
|
||||
IIS, domain name settings and network router configuration and security settings for external internet access are complex and require the assistance of a networking professional familiar with the process of exposing an IIS server to the internet.
|
||||
|
||||
Support and/or instructions for this process are highly equipment and situationally dependent and therefore beyond the scope of this manual or the support we can provide. If you are not familiar with this process it is highly advised to hire a professional to set that part up. We provide the instructions here 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 site and equipment specific steps best done by a network professional.
|
||||
|
||||
Note that external access should be configured _after_ AyaNova server is set up and working via IIS _inside_ the network and it may save time to have that ready before getting the assistance of a network technician to enable and _confirm_ outside access to AyaNova by configuring IIS to use HTTPS a domain name and appropriate port exposure through the router.
|
||||
|
||||
## 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](ops-config-environment-variables.md).
|
||||
|
||||
## Installation procedure
|
||||
|
||||
Follow the steps below **in the order** they are presented here.
|
||||
|
||||
### Enable IIS Internet Information Server
|
||||
|
||||
If you already have IIS enabled read through and verify the following instructions to **confirm** it is ready for AyaNova.
|
||||
|
||||
The steps to enable IIS vary by type of operating system:
|
||||
|
||||
#### Windows Server operating systems
|
||||
|
||||
(The following images are taken from a Windows Server 2019 operating system but the procedure is the same for any modern version of Windows server)
|
||||
|
||||
Enable the IIS server Role and selected Role settings:
|
||||
|
||||
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.
|
||||
|
||||
#### Windows Desktop operating systems
|
||||
|
||||
Enable the IIS Role and selected Role settings:
|
||||
|
||||
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.
|
||||
|
||||
### 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/](https://www.postgresqltutorial.com/install-postgresql/)
|
||||
|
||||
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](ops-config-environment-variables.md) after installing the AyaNova server.
|
||||
|
||||
### ASP.NET Core Runtime
|
||||
|
||||
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 6.0 or newer and it should be present **before** AyaNova is installed. Download the runtime here [https://dotnet.microsoft.com/permalink/dotnetcore-current-windows-runtime-bundle-installer](https://dotnet.microsoft.com/permalink/dotnetcore-current-windows-runtime-bundle-installer).
|
||||
|
||||
### AyaNova server installation
|
||||
|
||||
Once you have ensured the two pre-requisites above are installed and available; download and run the AyaNova network installer: [https://www.ayanova.com/Downloads/v8/ayanova-lan-setup.exe](https://www.ayanova.com/Downloads/v8/ayanova-lan-setup.exe). Follow the prompts to complete installation but **DO NOT** select to start AyaNova with Windows, IIS will be responsible for starting and stopping AyaNova.
|
||||
|
||||
#### Server configuration
|
||||
|
||||
The server **must** be configured before it will be able to start properly and find the database server.
|
||||
|
||||
The AyaNova installer will create a `config.json` file in it's program files folder (default is `c:\Program Files\ayanova\config.json`) as its 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=mypasswordforpostgres;Database=AyaNova;",
|
||||
"AYANOVA_DEFAULT_TRANSLATION": "en",
|
||||
"AYANOVA_BACKUP_PG_DUMP_PATH": "postgres\\bin\\",
|
||||
"AYANOVA_DATA_PATH": "%ProgramData%\\ayanova",
|
||||
"AYANOVA_LOG_LEVEL": "Info"
|
||||
}
|
||||
```
|
||||
|
||||
The `AYANOVA_DB_CONNECTION` property must be edited and where it has "mypasswordforpostgres" substitute the actual PostgreSQL password to be used. 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 IIS. 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.
|
||||
|
||||
#### Boot and test the server
|
||||
|
||||
It is important and necessary to confirm AyaNova is able to run properly _BEFORE_ the final configuration in IIS to connect to AyaNova. Follow the steps in this section carefully to confirm AyaNova is working before moving on the final step of configuration IIS below.
|
||||
|
||||
The AyaNova installer creates two shortcuts in the Start Menu under "AyaNova Server" and also on the Windows desktop titled "AyaNova server" and "AyaNova App". The AyaNova Server shortcut will start AyaNova by running AyaNova.exe in the program files folder where AyaNova was installed and 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 App shortcut is only relevant to this initial configuration testing, once AyaNova is confirmed to be working via IIS you will no longer access it directly but through IIS instead so the AyaNova App shortcut and address it uses will no longer be required and should not be used execept for diagnostic purposes only.
|
||||
|
||||
Start the server by using the "AyaNova server" shortcut on the Windows desktop. 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.
|
||||
|
||||
|
||||
|
||||
Use the AyaNova App shortcut to open the server and get started with AyaNova.
|
||||
|
||||
#### If the server closes immediately upon running with an error
|
||||
|
||||
In some cases where a critical configuration value is completely missing, the server console may display the error but close too quickly to read it. In this case you can view the message by starting AyaNova.exe manually from a command line prompt. For example if AyaNova is installed to the default location open a command prompt (press WIN-x, select "command prompt" from the menu) and type `"c:\Program Files\ayanova\AyaNova.exe"` (note the quotation marks) to run AyaNova and see the error and make the necessary changes.
|
||||
|
||||
Only after you have confirmed that AyaNova server is working and you can login should you proceed to the next step of enabling IIS to work with AyaNova.
|
||||
|
||||
### IIS AyaNova site configuration
|
||||
|
||||
At this point there is a working AyaNova server and all that is left is to set up a Site within IIS management console to host AyaNova in IIS so users can access AyaNova from inside or outside of your network.
|
||||
|
||||
Stop AyaNova server if it is still running from the previous step by following the instructions in the server console window. From this point on IIS will be controlling the starting and stopping of the AyaNova server.
|
||||
|
||||
- Open IIS manager:
|
||||
|
||||
From a server version of Windows:
|
||||
Tools->Manage menu item from server manager:
|
||||
|
||||
|
||||
From a non-server version of Windows:
|
||||
Access IIS manager from the Start menu Administrative tools menu item:
|
||||
|
||||
|
||||
- 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.
|
||||
|
||||
- Edit Application Pool
|
||||
Under the Server's node in the connections panel select Application Pools right click the sites application pool which will have the same name as the Site name configured in the previous step and select "Basic settings" from the context menu:
|
||||
|
||||
|
||||
In the application pool dialog set the .NET CLR version to "No Managed Code":
|
||||
|
||||
(this may seem counterintuitive since AyaNova uses .net but AyaNova uses .net Core, not the .net referred to here)
|
||||
|
||||
Click on Ok to save and continue to the next step
|
||||
|
||||
- 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 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 hosting bundle setup again that was installed previously (repair installation) to ensure it recognizes IIS and enables proper operation.
|
||||
|
||||
### Starting and stopping AyaNova server
|
||||
|
||||
IIS will automatically manage starting and stopping AyaNova as required.
|
||||
|
||||
### 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 the correct port and optionally 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.
|
||||
|
||||
For Server Operations role review the [Server operations](ops-intro.md) configuration and maintenance guide.
|
||||
|
||||
For the Business administration role review the [Getting started](adm-getting-started.md) guide for Administrators.
|
||||
Reference in New Issue
Block a user