Publish through IIS

The engine now answers on its own HTTP port. Users reach it through the IIS that already serves DocuWare, on the same host name, under /ivy.

Tip

Important

Do not use axonivy-market/iis-proxy here. It assumes IIS serves nothing but Ivy: it routes all traffic to the engine and changes authentication for the whole site, which breaks DocuWare. The damage is done by the run and cannot be repaired afterwards. Use the DocuWare script, which is scoped to /ivy and nothing else.

Download the scripts

docuware-ivy-iis-proxy.zip

Extract it on the Windows server that runs DocuWare — the commands below assume you are in the extracted scripts\ folder. It contains:

File

What it is

scripts\Set-IisIvyProxy.ps1

The script that publishes Ivy under /ivy

scripts\Backup-IisConfiguration.ps1

Takes the backup to run first

scripts\Restore-IisConfiguration.ps1

Puts IIS back

SCRIPTS.md

Every parameter of all three, and what each one changes

RISKS.md

What has not been evaluated, and what to decide before going live

README.md

The guideline these scripts belong to

Before you start

Four things have to be true. The first is already done for you.

What

Detail

The engine serves under /ivy

Shipped that way. IIS forwards the path unchanged; nothing to do.

BaseUrl is set

Customer-specific, so it ships commented out in config/ivy.yaml. Set it to https://<public-host>/ivy — it must end with the same /ivy.

The licence covers the public DNS name

Give every public name to the DocuWare Ivy team when you request the licence. Ask early: without it the engine answers 400 to everything.

Application Request Routing 3.0 is installed

URL Rewrite is already on a DocuWare server; ARR is not. The script refuses to run without it rather than installing it.
Note
The public host name is registered in five places

They are independent, and none of them fails at the moment you make the change. Changing the public name means changing all five in the same maintenance window.

Where

What a wrong or missing value looks like

The licence

HTTP 400 on every proxied request

BaseUrl in ivy.yaml

browsing is fine; the links in mails point somewhere wrong

The IIS binding and its certificate

404 for that name, or a certificate warning

The identity provider's app registration

sign-in fails at the provider, with an address mismatch

DocuWare's own configuration

DocuWare's Web Client login fails on that name only

Run the script

In an elevated PowerShell session on the Windows server, in this order:

.\Backup-IisConfiguration.ps1 -Label pre-ivy-proxy
.\Set-IisIvyProxy.ps1 -WhatIfOnly
.\Set-IisIvyProxy.ps1 -IvyHost <linux-host> -IvyPort 8080 -PublicHost <public-host>

The second line changes nothing and prints what the third will do. Take a fresh backup even if an older one exists: a rollback restores the site configuration as it stood in that set, so anything added since is lost with it.

What it changes:

  • two rewrite rules at the top of the site's web.config, matching /ivy only

  • X-Forwarded-Proto: https, which the engine needs because IIS terminates TLS and forwards plain HTTP

  • the upload limit for /ivy only, raised to 100 MB

  • one server-wide ARR setting, reverseRewriteHostInResponseHeaders, which must be false or no external sign-in can complete

It touches no existing rule, binding, certificate or authentication setting. Running it twice replaces only its own rules.

Tip

Important

Plan a maintenance window. Installing ARR restarts the web service, and a rollback reloads the IIS configuration. Both interrupt DocuWare briefly.

Verify

Four checks. The last two are the ones that catch a setup which otherwise looks fine.

  1. The portal loads with its styling at https://<public-host>/ivy/docuware/project-ivy/. Check it in a browser: curl answers 200 on a working and a broken setup, because the first response is a small redirect stub.

  2. DocuWare still answers at https://<public-host>/DocuWare/Platform. Allow for a slow first request on an idle server — retry before believing an error.

  3. A full DocuWare login completes, not just a page load. ARR settings are server-wide and login is the most sensitive path.

  4. A task notification mail whose link works from a client machine. This is the only check that exercises BaseUrl.

Two limits IIS imposes

Both apply to every request through IIS, and neither can be lifted from the engine's side.

Limit

What to do

A request is cut off after 2 minutes

This is ARR's timeout and it is server-wide, so the script does not change it. If a customer needs longer, either give Ivy its own ARR server farm, which carries its own timeout, or raise the machine-wide value with DocuWare's agreement: appcmd set config /section:system.webServer/proxy /timeout:00:30:00

Uploads over 100 MB are refused

The script sets this for the /ivy path only, so DocuWare keeps its own limit. Pass -MaxUploadBytes for a different value.

Roll back

.\Restore-IisConfiguration.ps1 -List
.\Restore-IisConfiguration.ps1 -SetName <set> -Mode Files -Only site
Note

Note

The restore asks for confirmation before it changes anything, which is what you want at a console. Running it from a script or a remote session with no console, it waits for an answer that never comes and appears to hang. Add -Confirm:$false there.

If something goes wrong

Symptom

Cause

Fix

HTTP 400 on every request under /ivy

The licence does not cover the public name

Add the name to Public URLs on the licence. Do not work around it by rewriting the host — the engine would then run on a URL its licence does not cover

HTTP 404 under /ivy

The context name does not match

The engine must serve under /ivy and the script must be run with the same context name

The portal loads as bare HTML, no styling

Asset URLs fall outside the proxied path

Check BaseUrl ends with /ivy and the rule was applied to the right site

Sign-in with an external provider never completes

reverseRewriteHostInResponseHeaders is true

Set it to false. The script does this; check it if the script was not used

Links in notification mails point somewhere wrong, browsing is fine

BaseUrl is wrong or unset

Set it in config/ivy.yaml and restart the engine

DocuWare's Web Client shows an error page after loading, Ivy works

Ivy is published on a host name DocuWare was not configured with

Publish Ivy on DocuWare's own host name, or register the new name in DocuWare. Its Identity Service log is the only place that reports this

Users who arrive over http:// cannot sign in

The forwarded protocol always says https

Redirect port 80 to 443 on the site. The script warns when it finds an HTTP binding

A long-running task fails with a gateway error

The 2-minute ARR timeout

See the limits above

A large upload fails with an IIS error page

The upload limit

See the limits above

The proxied paths answer 500 after a rollback

The wrong restore mode was used

Restore again with -Mode Files -Only site