Deployment Guide
- Logan Korn
Overview
nFORM is an online electronic form submission and management tool that can be used to create and manage a wide variety of forms and workflows. This document covers the deployment of the nFORM application, and it may be used to setup a new installation or to upgrade an existing installation.
The nFORM application is a complicated piece of software and provides a variety of methods for customizing its functions, appearance, and behavior. This document assumes that you already have database, application, and configuration packages from Windsor Solutions in-hand, these are typically provided to the customer by Windsor Solutions prior to the initial deployment of nFORM.
Introduction
Installing or upgrading nFORM is straightforward. The primary steps include:
Shut Down nFORM Application
Setup nFORM Database
Move nFORM Application to Web Server
The main difference between a new installation and an upgrade is that you need to setup your web server and database. In an upgrade scenario these already established. For new installations the initial configuration will be provided to you by Windsor Solutions.
Shut Down nFORM Application
If you are performing an upgrade to your nFORM application or database, make sure that you have stopped the running nFORM application. If your web server only hosts the nFORM application, you can simply shut down Microsoft Internet Information Server. Typically, this is done by logging onto the server running IIS and then launching the “Internet Information Services (IIS) Manager” application. When this application opens, you can select your web server from the list in the right-hand pane and then click the “Stop” link that is listed under the “Manage Server” section in the right-hand panel.
Often your web server will be hosting more than one application. In this case you will want to stop only the “application pool” that supports the nFORM application. In the IIS Manager application, you will want to click on the disclosure triangle to the right of your server in the right-hand panel. This will display all the resources linked to your server, click on the “Application Pools” item and a list of the pools setup on your server will be displayed in the main, central panel. Next click on the application pool that supports your nFORM installation to highlight it in the list, a set of links will appear in the right-hand panel under the header “Application Pool Tasks”. You may click on the “Stop” link to stop the application pool, thus stopping the nFORM application.
Setup nFORM Database
New nFORM databases are created by restoring the minimal database provided by Windsor Solutions. This database provides not only the structure that the nFORM application requires as well as some seed data that the application is expecting to find. When nFORM is being upgraded, we will provide a database package that may be used to upgrade an existing nFORM database. You may then run this package against your existing database to upgrade it to the current version, if required.
Microsoft SQL Server Account and Database Privileges
We recommend that you create a new Microsoft SQL Server account specifically for nFORM. The account name and password for this account may then be added to the nFORM configuration and nFORM will use that account to access the database. The account should have the ability to read, write and alter the structure of the database. With those privileges in place, you may also use this account to perform upgrades on the database.
Creating new nFORM Database
We recommend that you copy the backup file for the new nFORM database to your database server. The default location for backup files for Microsoft SQL Server is deep inside the installation directory.
C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\MSSQL\Backup
Your location may be different, depending on how your database server has been setup and configured. If you aren't sure, ask your database administrator for the correct location.
Once you have the backup file in place, you can connect to your database server with the “Microsoft SQL Server Management Studio” application. You will need to connect with an account that has the appropriate rights to create a new database and to restore from backups. When the application opens, click the icon to the right of your database server's name in the right-hand panel to see a list of the resources associated with your database server. Right-click on the “Databases” entry and select the “Restore Database…” item from the menu.
The “Restore Database” window will appear. We are restoring from a backup file, set the “Source” to “Device” and then click the button with the ellipses (“…”) to select the file. The “Select Backup devices” window will appear, click on the “Add” button to open the file browser. From there, browse to the backup file and select it by clicking on its name and then pressing the “OK” button. You can then press “OK” to close the “Select Backup Devices” window and the “Restore Database” window will update to indicate that it is ready to restore the database.
The last step is to set the “Destination”, in most cases the name of the database will be “nForm” but you are free to choose any name you feel is appropriate. With the destination set, press the “OK” button at the bottom of the window to restore the database.
The only other thing to note is that the SQL Server account that is used by nFORM should have its default schema set to the schema that contains the nFORM tables and objects. In typically deployments this schema is named “nForm”.
Notes on the “nForm” Schema
When nFORM seed database is reseeded in the environment, all the required database objects are created. This includes accounts and schemas. All nFORM databases include a schema named “nFORM” and the account that nFORM uses this schema set as its “default” schema.
Should you need to re-create the account used by nFORM, be sure that its “default” schema is also set to “nForm”. In this way the new account will look in the correct schema for database objects.
Upgrading the nFORM Database
The first step is to unpack the database package on a machine that has local network access to your database server. It is strongly encouraged to backup the existing nFORM database before running the package. While we do test the database package in a wide variety of scenarios, it always makes sense to be cautious. Also, you will want to stop the running nFORM application before running the database upgrade package.
To apply the script changes, we will be using the flyway command line tool. To apply the package, use a command prompt or powershell session to navigate to an established flyway application that has been configured to work with your database. You will place the sql package in the sql folder, and then run the command, flyway migrate. The package will then run to update your database to the latest version.
Move nFORM Application to Your Web Server
With our database in place the next step is to move the contents of the nFORM deployment package to our web server. We will also need to move in our configuration as well as create a new website for nFORM. When we upgrade an existing installation, we backup that installation and then move the contents of the nFORM deployment package into place, overwriting the previous installation.
Deploying nFORM for the First Time
Our first deployment of nFORM to a new web server can be broken down into three steps.
Install required software on the web server (Application Initialization and the .Net Framework package)
Creating a new Application Pool and Web Application
Moving the contents of the nFORM package into our new website
Each of these steps is simple and straightforward, the important thing is that we do them all and that we do them in order. At no time will we put the web server itself at risk, the worst outcome is that our new nFORM install doesn't function.
Installing Required Software on the Web Server
First, we want to make sure that the “Application Initialization” feature is installed on our web server. With this feature installed we can configure the web server to start the nFORM application as soon as the web server starts. This will ensure that nFORM is always running and available. Second, we will install the .Net Framework package so that the web server can host the nFORM application.
Log into your web server and launch the “Server Manager” application (on most servers, this application will launch automatically when you log in). When Server Manager finishes opening, click on the “Manage” link in the upper right-hand corner of the window and select the “Add Roles and Features” option.
The “Add Roles and Features” wizard will open and display some explanatory text about how the wizard works. Click the “Next” button to move to the next step.
You will be asked to select the installation type, click radio button for the “Role-based or feature-based” installation and then click “Next” to continue.
On this next screen you will be asked to select the server on which to perform the installation. Typically, the only server in the list will be yours, select it and then press “Next” to continue.
The “Server Roles” page will appear, and in most cases, the “Web Server (IIS)” role will already be installed. If it's not, go ahead and check the box next to the “Web Server (IIS)” role. The only other box we want to check is the one for “Application Initialization”, we can leave the rest of the items with their default value. Click the disclosure triangle to the right of the “Web Server (IIS)” entry to display its children. Do the same with the “Application Initialization” entry and then check the box for the “Application Initialization” option. With that done, press “Next” to move to the next step.
We don't need to make any changes to the “Features” panel, simply click “Next” to continue. Confirm that you would like to enact these changes and then complete the wizard. It will take a couple minutes to install these features and then you will be all set.
Install .Net Framework Package
Version 4.8 of the .Net Framework will need to be installed to run the application on the web server. Typically, nFORM targets the newest version of .Net Framework, at the time of this writing that version is 4.8. You can download the installer from Microsoft's .Net website.
Once the package is downloaded, move it to your web server and double-click it to install. There are no configuration options, simply click “Next” to move through the descriptive panels and to install the package.
Create a new Application Pool
Now that our web server is set, we need to configure it to host the nFORM application. First, we want to create a new “Application Pool” to support the nFORM application. This lets us manage the web server resources that support nFORM separately from the web server as whole.
Log into the web server and then open the “Internet Information Services (IIS) Manager” application. After it launches you will see your web server listed in the right-hand panel. Click on the small disclosure triangle to the right of your web servers name to view the resources associated with your web server. Click on the “Application Pools” entry and a list of your current application pools will be listed in the main, central panel. Click on the “Add Application Pool…” link at the top of the far right-hand side panel.
The “Add Application Pool” window will appear, fill in the name with “nform” or any value you feel is appropriate. The “.Net CLR Version” should already be set to the name of the earliest supported version of the .Net Framework. Yes, it's very odd; as of this writing the version should be set to something similar to “v4.0.30319”. Set the “Managed Pipeline Mode” to “Integrated” and then check the box labeled “Start application pool immediately”. Lastly, press the “OK” button to save these changes and create the new application pool.
You might think we were done, but there is one more step. Click on the nFORM application pool in the list in the main panel and then click the “Advanced Settings…” link in the far right-hand column. The “Advanced Settings” window will appear, click on value for “Start Mode” in the “(General)” section and set it to “AlwaysRunning”. Change the “Limit (percent)” value in the “CPU” section to zero and the “Limit Action” to “NoAction”. Lastly, change the “Idle Time-out (minutes)” in the “Process Model” section to “0”.
Press the “OK” button to save the “Advanced Settings”.
Create a new Website
We need to create a new website that will use our application pool and will host the nFORM application. You should be logged onto your web server and have the “Internet Information Services (IIS) Manager” application open. In the right-hand panel should be a list of web servers, select yours from the list and click on the small triangle to the right of its name to display all of the resources associated your web server.
To create a new website, right-click on the “Sites” icon and click on the “Add Website…” item.
The “Add Website” window will appear. Type in “nform” into the “Site Name” field or use any name you feel is appropriate. Click on the “Select…” button to the right of the “Application Pool” field and select the application pool that you created for nFORM.
Next, click on the “…” button to the right of the “Physical Path” field. Browse to the location where you'd like to store the application files for nFORM. It is recommend to open the “Local Disk (C:)” drive and click on the “inetpub” folder to select it. Click on the “Make New Folder” button to create a new folder in the “inetpub” directory and name that folder “nform” (or any name you feel appropriate). Select that new folder and then press the “OK” button to choose it as your “Physical Path”.
The “Binding” and “Host name” field will vary for each installation. If your web server has an SSL certificate installed for nFORM, you can choose “https” from the “Type” menu and then choose the “IP Address” that has been assigned to nFORM (or “All Assigned” if this server only hosts the nFORM application). In the same way, if you have a host name that has already been assigned to your web server, type that into the “Host name” field.
Make sure the “Start website immediately” button is clicked and then press the “OK” button to create the new website for nFORM. The website will be created and add to the list of websites.
Now that our website has been created, we want to give the nFORM application pool the appropriate rights to the directory (the “physical path”) that houses nFORM. This will enable nFORM to write to files in this directory, for instance log files. Open the “File Explorer” and navigate to the “C:” directory and then right-click on the “nform” folder. Select the “Properties…” item from the menu.
The properties window for the folder will appear. Click on the “Security” tab to see the current security settings for the folder. Next, click on the “Edit” button to change the current set of permissions. The “Permissions” window will appear, click on the “Add…” button to add a new permission to the folder.
The “Select Users or Groups” window will appear. Click on the “Locations…” button and double-click the name of your web server to set that as the location from which we will choose an account and then click the “OK” button. Next, type “IIS AppPool\” (or whatever you named the nFORM application pool) into the “Enter the object names to select” field. With that set, press the “OK” button to add the new account to the permissions list.
The name of the application pool should now be listed in the top portion of the permissions window. Click on that name once to select it and then check the checkbox in the “Allow” column for the “Full Control” row. This will enable nFORM to read and write to files in this directory. With that complete, press the “OK” button to save these changes, as well as the “OK” button in the properties window.
Move nFORM Application Files
Our last step is to move the contents of the nFORM distribution into the new directory for the website. This is often a two-step process, typically nFORM is distributed in two bundles: the application bundle and the configuration bundle.
Log into your web server and unpack the nFORM application package, you will see contents similar to the list pictured below.
Copy all of these files to the nFORM directory on your web server. You can select them all and then drag them to your directory on the web server. It will take a minute to copy them over.
Next, unpack the configuration bundle. This bundle will contain a single directory called “Conf”. Rename the “Conf” directory in the nFORM directory on the nFORM server to “Conf.dist” and then copy the “Conf” folder from the configuration bundle to the nFORM directory on the web server.
With nFORM and the configuration bundle deployed the only remaining step is to re-start the application pool for nFORM. This will ensure that all the configuration changes in the application bundle are picked up. Open the “Internet Information Server (IIS) Manager” application and click on the disclosure triangle to the right of your server in the right-hand panel. This will display all the resources linked to your server, click on the “Application Pools” item and a list of the pools setup on your server will be displayed in the main, central panel. Next, click on the application pool that supports your nFORM installation to highlight it in the list, a set of links will appear in the right-hand panel under the header “Application Pool Tasks”. You may click on the “Restart” link to stop and then restart the application pool, thus stopping and restarting the nFORM application.
That is it! Your nFORM installation is now complete.
Upgrading an Existing nFORM Deployment
Before upgrading your nFORM deployment, we strongly encourage you to backup your current deployment. This is an easy process, all you need to do is log into your web server and navigate to the folder that holds your nFORM installation, typically this is located in the “C:\” directory and named “nform”. Click on that folder and then copy and paste it to create a backup. It is good practice to the rename the copied folder from “nform Copy” to “nform-MM-DD-YYYY” where “MM-DD-YYYY” represents the current date.
Next, unpack the nFORM application package. The contents of this package should look similar to the image below.
The “Conf” directory in the application package contains a sensible default configuration but it is unlikely that this is the configuration you want to use. Change the name of the “Conf” folder to “Conf.dist”. Next, copy and paste these files into the nFORM directory on your web server. When you are prompted by the File Explorer, choose to “overwrite” the existing files with the new ones from the application package.
If a new configuration package is received, follow a similar process. Unpack your configuration package, it should contain one directory called “Conf”. Copy and paste the “Conf” folder into your nFORM directory on your web server. When you are prompted by the File Explorer, choose to “overwrite” the existing files with the new ones from the application package.
With the database updated and the new files deployed, the last step is to start the web server. If you had stopped your web server at the beginning up the upgrade process, go ahead and restart it. If you only stopped the nFORM application pool, restart that application pool now.
Once the web server or application pool has finished restarting, your new nFORM deployment will be ready for use!