Install the Web App

On this page

Installing the Web App package and publishing a Web App instance are two separate acts. The package installs a template; the Web Configuration tool then creates an IIS site or virtual directory from that template.

The Web Portal Link system macro, which an instance's URL page can set when the instance is created, is edited afterward in the Settings App, in its Links group; see Link macros.

Before you begin

  • You need a Database Access Key for the database the instance uses. The wizard's Database page lists the registered keys and can import one.
  • The URL of a new instance must start with https://. The wizard's URL page, which you see when you create an instance, accepts no other address.
  • The web server needs the IIS components listed in System Requirements.

Install the Web App package

After the Web App package is installed, its finish page offers Run the Web Configuration, which opens the Web Configuration tool to create an instance from the installed template. The offer is not made in these cases:

  • The package is already installed.
  • The setup runs as an evaluation installation.
  • The installation is an administrative (network-image) installation.
  • A major upgrade was detected. In this case the package still runs the tool, which recreates the instances from their saved configuration instead of asking for the settings again.

On an upgrade, the package's Files Backup page states that the upgrade replaces all files and offers to back up the instance files. The backup check box is selected by default, and the backup folder defaults to a dated subfolder of Backups\ under the installation directory. Customized instance files survive only in that backup, with one exception: a hand edit to the instance's Web.config survives an upgrade when it sits between the XML comments BEGIN_CUSTOM_EF677073_10AC_44FE_AF1F_2AED27E06048 and END_CUSTOM_EF677073_10AC_44FE_AF1F_2AED27E06048 placed directly under the root element. After the upgrade, that span is restored at the end of the root element.

In the Web Configuration tool

To create an instance from the tool itself, choose File > Create > Web App.

Pre-configuration considerations

Configuring a Web App instance settles four things:

  • Database: how the instance connects to the database, by importing a Database Access Key.
  • Web: whether the instance is a web site of its own or a virtual directory, and on which site.
  • The end-user authentication method of the instance.
  • The link macro, Web Portal Link, that workflow notifications use to address this instance.

For an instance behind a reverse proxy or load balancer, the host header setting names an HTTP header, not a host, and the Web App uses that header's value as its external address. The setting is on the Application Gateway tab; see Web App Settings.

Create an instance

When you create an instance, the wizard runs its pages in this order. The Virtual Directory page is skipped when you install the instance as a web site.

  1. On Database, choose a registered Database Access Key in Key, or click Import Key.... Review SQL Server and Database, and click Next to test the connection.
  2. On Installation Type, choose Install as a Web site or Install into a virtual directory.
  3. On the Web Site page, select Choose an existing site: and pick the site, or select Create a new site with the following parameters: and fill in Site Name, IP Address, Host name, Port, and Physical Path. A new site's folder defaults to one named after the site, with a number appended when that folder already exists. An instance installed as a web site defaults to the folder ...\WebApps\Web\<site name>\root, with a number appended when that folder already exists.
  4. If you chose a virtual directory, enter its name and review Physical Path on Virtual Directory. When using an existing site, you can also select a directory already published under it.
  5. On the Authentication Method page, choose the end-user authentication method. For the choices the page offers, see Publish the Web Applications; for how the methods work, see Authentication Methods.
  6. On URL, review the generated HTTPS address. If it differs from the Web Portal Link system macro, choose which value to keep:
    • Update system macro with instance URL saves the instance URL to the macro when you apply the settings.
    • Update instance URL with system macro copies the macro into the URL box.
  7. On Ready to Apply Settings, review the summary and click Apply. Use Previous to correct a choice before applying it.

For field validation, default folders, and the pages shown in each mode, see The publishing wizard.

When you apply the settings, an empty Web Portal Link macro is filled with the instance URL. You can copy the summary on the last page with Ctrl+C or from its shortcut menu.

Reconfigure an instance

Right-click the instance in the tool's tree and choose Configure, then Full, Database, or Web.

  • Full and Database start on the Database page. Web starts on the Installation Type page and skips the Database page.
  • A Database run restarts the web application when it applies the settings.
  • A reconfigure does not show the URL page. A Full or Web run fills an empty Web Portal Link macro but does not change a macro that already holds a value, and a Database run does not change the macro.
  • A hand edit to the instance's Web.config that sits between the two marker comments survives a reconfigure; the span is moved to the end of the root element.