> THIS PAGE IS OUTDATED AND WILL BE UPDATED SOON TO REFLECT THE INSTRUCTIONS FOR VERSION 8.x.y INSTRUCTIONS. PLEASE USE DOCKER INSTEAD.

# Windows Server 2019 Installation Guide

This page describes the procedure for a CDP4-COMET Webservice for IIS initial installation how to install updates on Windows Server 2019.

## Prerequisites
- .NET Framework 4.7.2 needs to be installed on the server
- A PostgreSql version 12.x CDP4-COMET database server should be accessible from this server.

# Postgres Installation

- Download the latest PostgreSql version 12.x release from the [PostgreSql download website ](https://www.postgresql.org/download/).
- Install PostgreSql version 12.x
   - Make sure that all components that can be installed in the installation are installed.
   - Don't forget the admin user password that you need to define during installation. We need it for later use.
   - Leave the option `Default Locale` when asked for a locale to use for the database cluster.
- After PostgreSql installation, make sure that the PostgreSql database can be accessed from the server where the CDP4-COMET Webservice for IIS will be running.
- Download the [PostgreSql initialization script](https://github.com/STARIONGROUP/COMET-Docker/blob/development/cdp4-database-community-edition/cdp4server.sql) and save it somewhere on disk (<FileLocation>\cdp4server.sql).
- Run the PostgreSql initialization script as a PostgreSql admin user using psql, which is located in the `Program Files\PostgreSQL\12\bin` folder:
    -  `psql -h localhost -U postgres -p 5432 -q -f <FileLocation>\cdp4server.sql`

<br/><br/>

# IIS Installation
The CDP4-COMET-Webservice for IIS requires IIS to be installed with ASP.NET 4.7.2 or higher.

> The server needs to be restarted during the installation process.

### Server Manager
If Internet Information Services isn't already installed on the server, then we need to add it using the "Add roles and features" option in the Server Manager.

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-01.png">

>- Confirm using `Next` button

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-02.png">

>- Select `Role-based or feature-based installation`
>- Confirm using `Next` button

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-03.png">

>- Select the correct Server, or virtual hard disk. 
>- Confirm using `Next` button

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-04.png">

>- Select the option `Web Server (IIS)`
>- After you select this option a dialog pops up (see image below)

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-05.png">

>- Confirm installation of IIS Management Console by clicking `Add Features`

---
<br/><br/>

---
At this point the `Web Server (IIS)` option will be selected.<br/>
Depending on previous installations, the option can be expandable (Image 1 below), or not (Image 2 below).

**Image 1**

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-06.png">

In case the option is expandable immediately, please select ASP.NET 4.7 (or higher) under `Web Server => Application Development` together with `ISAPI Extensions` and `ISAPI FIlters`.
>- Confirm using `Next` button

**Image 2**

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-11.png">

In case the option is NOT expandable immediately then after the IIS installation is done, we need to execute `Add roles and features` in the Server Manager a second time and select the option as shown in Image 1 (see above) to finish the installation.

>- Confirm using `Next` button

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-07.png">

>- Select the option `ASP.NET 4.7` (or higher)
>- Confirm using `Next` button

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-08.png">

>- Confirm using `Next` button

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-09.png">

>- Select the option `Basic Authentication` under `Web Server => Security`
>- Confirm using `Next` button

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-10.png">

>- Confirm using the `Install` button

IIS will now be installed and when it is finished the server should be restarted. 
Depending on previous steps we might need to run the installation again (see image 1 and image 2 above).

---
<br/><br/>

---
## Install CDP4-COMET Webservice for IIS
Although the CDP4-COMET Webservice can be added to an existing IIS Website (root, and subfolder), for this installation manual we have chosen to create a new Website and install the CDP4-COMET Webservice in its root folder. 

### Create Website

>- Open IIS Manager

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-12.png">

>- Right click on the `Sites` node and choose `Add Website` from the menu  

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-13.png">

>- Choose a Site name
>- Choose the Application pool (preferred way is to create a new Application pool for optimal execution isolation of the CDP4-COMET Webservice)
>- Choose the physical path to the CDP4-COMET Webservices' location on disk. 
>- Set the binding data as preferred

---
<br/><br/>

---
### User Access rights
The user that is defined in the Application Pool that was created for the web site should have correct access to the comet-webservice folder:

- Modify
- Read and execute
- List folder contents
- Write

For more information on IIS user access see [Microsoft Documentation on Application Pool Identities](https://docs.microsoft.com/en-us/iis/manage/configuring-security/application-pool-identities) 

---
<br/><br/>

---
### Add Files to Website

Download the latest `COMET-Webservices-IIS-x.x.x.zip` file from [CDP4-COMET Webservice releases](https://github.com/STARIONGROUP/COMET-WebServices-Community-Edition/releases)

>- Extract the files from the latest CDP4-COMET Webservice for IIS zipfile to the root folder of the website we defined in a previous step.

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-14.png">

The end result should be that the root folder contains two `.config` files and a `Bin` folder

---
<br/><br/>

---
### bin/config.json

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-15.png">

In the Bin folder you can find a file `config.json.new`.
This file contains the CDP4-COMET Webservices' application settings.
It is however not the file that will be used at runtime. 
For that to be the case we need to **rename the file** to `config.json`.

The reason for this manual step is that we do not want to overwrite the config.json settings during **updates**. In every CDP4-COMET-Webservices for IIS zip file, a new version of the `config.json.new` file can be found that can be used as a reference to update the `config.json` file.

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-16.png">

---
<br/><br/>

---
After renaming `config.json.new` to `config.json` we open the file, for example using notepad.

The only thing that needs to be changed is here is the Backtier section according to the CDP4-COMET (Postgres) database installation.

Don't forget to save the file.

### web.config (and parent config files)
> Please do not change the web.config file. The file gets overwritten on every update.

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-17.png">

Changes to parent (web server) config files are necessary for the CDP4-COMET Webservice for IIS to execute correctly.

To make these changes, please open the Configuration Editor (right panel) at the `WebServer level` as indicated in the left panel in the above image.

---
<br/><br/>

---
<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-18.png">

On the WebServer level in IIS, certain config values are locked for changes in deeper hierarchycal configuration levels ([Microsoft Documentation on IIS config file hierarchy](https://docs.microsoft.com/en-us/iis/get-started/planning-your-iis-architecture/iis-7-and-iis-8-configuration-reference)).

We need to unlock the following sections:

- system.webServer.httpRedirect
- system.webServer.modules
- system.webServer.handlers

Unlocking can be done by selecting the section using the dropdown selector at the top of the Configuration Editor panel and selecting `Unlock Section` from the `Actions` (right) panel.
If the section is unlocked successfully, you will see the option `Lock Section` instead of `Unlock Section` in the `Actions` panel.

Don't forget to Apply the changes.

If you browse to the website, the CDP4-COMET Webservices' Welcome page should show. 

---
<br/><br/>

---
# Updates
Updating the CDP4-COMET Webservice for IIS works pretty much the same as installing it for the first time.

### Update Website files

Download the latest `COMET-Webservices-IIS-x.x.x.zip` file from [CDP4-COMET Webservice releases](https://github.com/STARIONGROUP/COMET-WebServices-Community-Edition/releases)

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-14.png">

>- Extract the files from the latest CDP4-COMET Webservice for IIS zipfile to the root folder of the IIS Website.

<br/>

The end result should be that the root folder contains two `.config` files and a `Bin` folder.

---
<br/><br/>

---
### bin/config.json

<img src="https://raw.githubusercontent.com/wiki/STARIONGROUP/CDP4-WebServices-Community-Edition/windows-2019/windows-2019-15.png">

After the update, in the Bin folder you can find a file `config.json.new`.
This file contains the latest version of the CDP4-COMET Webservices' application settings.
It is however not the file that will be used at runtime. 
The `config.json.new` can be used as a reference to update the existing `config.json` file.