Differences

This shows you the differences between two versions of the page.

--- emis_systems_administrator_manual [2023/10/18 13:10] – [Deploy the Application] ghachey
+++ emis_systems_administrator_manual [2024/04/10 05:34] (current) – [Deploy the Application] ghachey
@@ Line 21: / Line 21: @@
 Currently only the Windows operating system is supported. The application can be installed on any recent version of the Windows operating system.
-  * Windows Server 2022, 2019, 2016
+  * Windows Server 2022 (recommended), 2019, 2016
   * Windows 11, 10
@@ Line 30: / Line 30: @@
 The only database engine currently supported is Microsoft SQL Server (SQL Server) with most deployments tested with the following versions:
-  * SQL Server 2022 (including Express Edition)
+  * SQL Server 2022 (including Express Edition) (recommended)
   * SQL Server 2019 (including Express Edition)
   * SQL Server 2014 (including Express Edition)
@@ Line 38: / Line 38: @@
 There is no need for an expensive license, the Express edition which is freely available will work fine for most small countries. If you don't have already a commercial license download the free version [[https://www.microsoft.com/en-us/download/details.aspx?id=29062|MS SQL Server Express]]. Any of the files would have the required minimal database engine but might has well download the 64bit full version called //ENU\x64\SQLEXPRADV_x64_ENU.exe//. Double click and follow through the installation. Choosing the default values is a good start and reboot the system when done.
-<note tip>For better backup plans of the SQL database (e.g support for compression) the paid version is recommended.</note>
+<note tip>For better backup plans of the SQL database (e.g support for compression) the paid version is recommended. However, we have a nice PowerShell script combined with a Windows Schedule Task that can easily automate DB backups also.</note>
 ==== Install .NET Framework ====
-Install [[https://www.microsoft.com/en-us/download/details.aspx?id=48130|.NET 4.6 Framework]] by downloading the web installer and running it, of course a good Internet connection will be required.
+The projects in the whole solution target either 4.6, 4.6.1 and 4.6.2. The migration to target 4.8 in each project is on-going. But the compiled solution runs fine in the default .NET that comes with the operations system and there should be no need to install another .NET version.
-<note tip>The installation might not proceed with a message that this or a later .NET framework is already installed on the computer. This is normal.</note>
 ==== Create Account to Run the Application ====
@@ Line 105: / Line 103: @@
 {{ :sysadmin-manual:user-login-mapping.png?nolink |}}
-==== Web Server (IIS) ====
+==== Deploy the Application ====
 === Enable the IIS Role ===
+We first enable the IIS role to create the necessary folders where the app will be deployed.
 To enable to **Web Server (IIS)** on the Windows Server open the **Server Manager** and find **Add Roles and Features**. Find the **Web Server (IIS)**, enable it and make sure it contains the following minimum functionalities.
 {{ :sysadmin-manual:iis-role-features.png?nolink |}}
+=== Install Web Server Dependencies ===
+To avoid some minor loading errors within the IIS configuration section we can install the dependencies now as they might already be expected from the configuration in the app's Web.Config file. Currently installing the URL Rewrite should be enough https://www.iis.net/downloads/microsoft/url-rewrite.
+=== Deployment Method ===
+The application is deployed using a dropbox share. If you do not have an account create one on the [[https://www.dropbox.com|Dropbox website]] and install their dropbox PC application. Your account and the dropbox application should be accessible from both the development machine and the production machine where the Pacific EMIS is to be deployed. And your account should be given access to a share called **WebInstall** by one of the Pacific EMIS maintainers. Using your own dropbox account for this is fine to get started and test deployment (e.g. training purposes, practice on your own machine) but the actual real production deployment should be using one of the organisation's dropbox account, one perpetually accessible by the current technical responsible person of the organisation (e.g. admin, sysadmin, system are common accounts for this).
+=== Deployment Configuration ===
+The share **WebInstall** contains a folder called **Pineapples** which has the application. The Pacific EMIS software project maintainer is usually the one preparing this folder with the latest releases. Before moving to the next step this is a good time to create a folder to hold some key files for your country of deployment. For example, in RMI the folder **RMI-deployment-files** was created in the **WebInstall** share. This folder can hold among, other things, the logo (rename it miemis.png,) the lookups spreadsheet and the SQL script generated from the spreadsheet.
+Next you must edit the deployment configuration file called **Web.config**. You can find it in the dropbox **WebInstall** (e.g. **C:\Users\Administrator\Dropbox\wwwroot\WebInstall\Pineapples\Web.config**). Then open it and edit the following three section to configuration the databases access.  The example below is for Marshall Islands: it uses miemis-test for database name, miemis for context and the SERVERNAME\SQLINSTANCENAME will depend on the server it is being deployed on.
+<code xml>
+  <connectionStrings>
+    <!-- Connection to the Identities database , note the factory seetting below will generate this database if going "code first"
+    this connectin string is referenced in ApplicationDbContext constructor
+    -->
+    <add name="DefaultConnection" connectionString="Data Source=SERVERNAME\SQLINSTANCENAME;Initial Catalog=IdentitiesP;Integrated Security=True" providerName="System.Data.SqlClient" />
+  </connectionStrings>
+  <!--
+    For a description of web.config changes see http://go.microsoft.com/fwlink/?LinkId=235367.
+    The following attributes can be set on the <httpRuntime> tag.
+      <system.Web>
+        <httpRuntime targetFramework="4.5.1" />
+      </system.Web>
+  -->
+  <appSettings>
+    <add key="server" value="SERVERNAME\SQLINSTANCENAME" />
+    <add key="database" value="miemis-test" />
+    <add key="context" value="miemis" />
+    <add key="title" value="MIEMIS Online" />
+    <add key="ReportServerUrl" value="http://localhost:8080/reportserver" />
+    <add key="FileDb" value="d:\files\filedb"/>
+  </appSettings>
+</code>
+<code xml>
+   <parameter value="Data Source=SERVERNAME\SQLINSTANCENAME;Initial Catalog=IdentitiesP; Integrated Security=True; MultipleActiveResultSets=True" />
+</code>
+Note: the document library where incoming documents are stored (both for the teacher images, and upload files such as this) is specified by the AppSetting FileDb
+On your local system, you will need to :
+  * Create a folder for this (e.g. C:\fileDb )
+  * Make sure that the account running the EMIS apppool has CRUD and Create Folder permissions to this folder
+  * Set the web.config entry
+=== Deployment Copy to IIS inetpub ===
+Now use the **deploy.bat** script to copy files into the IIS folder (i.e. **C:\inetpub\wwwroot\**). You'll have to do it through the command line. From the Windows menu open the command prompt then change directory to the dropbox share and then run the script (ignore the warning at the end and press enter when presented with **pause**), should be something like this:
+<code>
+   > cd C:\Users\Administrator\Dropbox\WebInstall\Pineapples\
+   > deploy.bat miemis
+</code>
+This will create the folder **C:\inetpub\wwwroot\miemis** with most of the necessary application. Now will be put in the remaining missing files: the **Web.config**, **miemis.png logo** and the **Global.asax**
+files. If you have already put your logo into **C:\Users\Administrator\Dropbox\WebInstall\RMI-deployment-files** as instructed earlier then the following commands should copy the files in the right place (you could do it from the Windows Desktop too)
+<code>
+   > mkdir C:\inetpub\wwwroot\miemis\assets_local
+   > copy C:\Users\Administrator\Dropbox\WebInstall\Pineapples\Web.config C:\inetpub\wwwroot\miemis\
+   > copy C:\Users\Administrator\Dropbox\WebInstall\RMI-deployment-files\miemis.png C:\inetpub\wwwroot\miemis\assets_local
+   > copy C:\Users\Administrator\Dropbox\WebInstall\Pineapples\Global.asax C:\inetpub\wwwroot\miemis\
+</code>
+You may have to give permission on the folder to the user running the IIS application pool (i.e. EMISWEB).
+{{ :sysadmin-manual:app-permissions.png?nolink |}}
+==== Web Server (IIS) ====
 === Create an Application Pool ===
@@ Line 133: / Line 210: @@
 {{ :sysadmin-manual:emis-application-pool-4.png?nolink |}}
-Next on the EMIS app, choose manage app and advanced settings;
+=== Add the Website (i.e. Web Application) ===
-{{ :sysadmin-manual:emis-application-pool-5.png?nolink |}}
+This step requires that you have already copied all the app's files to the **C:\inetpub\wwwroot\** folder.
-And change to run in your newly created Application Pool
+{{ :sysadmin-manual:emis-add-website-1.png?nolink |}}
-{{ :sysadmin-manual:emis-application-pool-6.png?nolink |}}
+Then complete the website's details as shown below.
-You may have to **Stop** and **Start** the application pool for this to take effect. Next, look for your new website in **Sites--Default Web Site**, in this case it is **miemis**. Right click it and **Convert to Application**, something that will look like the following.
+{{ :sysadmin-manual:emis-add-website-2.png?nolink |}}
-{{ :sysadmin-manual:iis-convert-app-pool.png?nolink |}}
+=== Add support for HTTPS ===
+Since this app has a strong security focus it automatically redirects to https from any http connection attempt. Therefore we must add support for https. First create a self signed SSL certificate in the IIS server.
+{{ :sysadmin-manual:emis-support-https-1.png?nolink |}}
+Give it details like follows.
+{{ :sysadmin-manual:emis-support-https-2.png?nolink |}}
+The newly added self signed certificate should look like this.
+{{ :sysadmin-manual:emis-support-https-3.png?nolink |}}
+Go back to our new website and edit the bindings.
+{{ :sysadmin-manual:emis-support-https-4.png?nolink |}}
+Add a new bindings for https like follows.
+{{ :sysadmin-manual:emis-support-https-5.png?nolink |}}
+It should results in something like this.
+{{ :sysadmin-manual:emis-support-https-6.png?nolink |}}
+Now when accessing the website to it's configured bindings you will see the following.
+<note tip>This is temporary as we will setup a verified SSL certificate later on eliminating this warning.</note>
+{{ :sysadmin-manual:emis-support-https-7.png?nolink |}}
 === Install missing modules ===
@@ Line 184: / Line 291: @@
+=== Change the Self-signed SSL certificate with a LetsEncrypt Verified SSL Certificate ===
-=== Secure using HTTPS and LetsEncrypt ===
+The easiest and cheapest way to remove the security from a self signed SSL certificate is to use LetsEncrypt. On windows you can install and run https://github.com/PKISharp/win-acme. Two things to do only.
-The easiest and cheapest way to encrypt the whole application is using the LetsEncrypt initiative. On windows you can install and run https://github.com/PKISharp/win-acme. Two things to do only.
   - Run to deploy the certificate the first time
   - Then setup a schedule task to renew every 3 months
-When HTTPS is working it is a good idea to redirect all HTTP (non-secured) traffic to HTTPS. This can be done using URL Rewrite as described at [[https://www.ssl.com/how-to/redirect-http-to-https-with-windows-iis-10/]]
+When HTTPS is working it is a good idea to redirect all HTTP (non-secured) traffic to HTTPS. While this is already done at the configuration of the application (i.e. Web.Config) it does not hurt to also do it at the web server level as described at [[https://www.ssl.com/how-to/redirect-http-to-https-with-windows-iis-10/]].
 ==== Setting Up Email ====
@@ Line 369: / Line 475: @@
   - Create ssh-keys with command ''ssh-host-config'' (mostly defaults are fine though some linux SSH experience is valuable here)
   - Do any edits to the ''/etc/sshd_config'' if you need (like changing SSH listen port)
-  - Start the SSH service with command ''net start sshd''
+  - Start the SSH service with command ''net start cygsshd''
   - Configure the backuppc user encryption keys with the command ''ssh-user-config''
   - Test ssh access with ''ssh backuppc@localhost'' and ''ssh backuppc@hostname''
@@ Line 394: / Line 500: @@
 === Automate daily SQL database exports ===
-This unfortunately can not "easily" be done with SQL Server Express (free edition), though there are ways. Here the steps outlined are with a licensed version of SQL Server.
+There are two ways to achieve this:
+  * The expensive paid version of Microsoft SQL Server can easily produce nightly backup plans from the UI.
+  * The free version of Microsoft SQL Server Express does not support this feature. However, it is not difficult to produce a script to do the backup and execute the script using the Windows Task Scheduler. This is the method used in most deployment of Pacific EMIS using a custom script on the server.
 === Automate daily JasperReports exports ===