From 62884229f8cc66fe0164b3eab580034ff90a3b8e Mon Sep 17 00:00:00 2001 From: Joe Dibley Date: Thu, 13 Aug 2026 03:06:37 -0700 Subject: [PATCH 1/3] Add installer log guidance for PingCastle Enterprise 4.0 Support needs installer logs when install fails or a case opens. Adds a Collecting Installer Logs subsection with the /l*v flag steps, and notes deep-linking to it from both install tabs. Co-Authored-By: Claude Sonnet 5 --- docs/pingcastle/4.0/enterpriseinstall.md | 8 ++++++++ docs/pingcastle/4.0/enterprisetroubleshooting.md | 12 ++++++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/pingcastle/4.0/enterpriseinstall.md b/docs/pingcastle/4.0/enterpriseinstall.md index 89adda72f3..d1dc3b792c 100644 --- a/docs/pingcastle/4.0/enterpriseinstall.md +++ b/docs/pingcastle/4.0/enterpriseinstall.md @@ -34,6 +34,10 @@ For SQL Express, visit [SQL Server Express Downloads](https://learn.microsoft.co #### Step 2 - Run PingCastleEnterpriseInstaller.exe (production) +:::note +Having trouble installing? See [Collecting Installer Logs](/docs/pingcastle/4.0/enterprisetroubleshooting#collecting-installer-logs) in the Troubleshooting guide. +::: + The installer wizard walks you through prerequisite checks, licensing, and configuration screens in the following order. 1. **Prerequisite check**: the installer checks the server for IIS and the ASP.NET 10.0 Hosting Bundle. If either is missing, it offers to install them for you. @@ -125,6 +129,10 @@ choco install sql-server-express #### Step 2 - Run PingCastleEnterpriseInstaller.exe (test/POC) +:::note +Having trouble installing? See [Collecting Installer Logs](/docs/pingcastle/4.0/enterprisetroubleshooting#collecting-installer-logs) in the Troubleshooting guide. +::: + 1. Run PingCastleEnterpriseInstaller.exe. The installer checks for IIS and the ASP.NET 10.0 Hosting Bundle and offers to install them if they're missing. :::warning diff --git a/docs/pingcastle/4.0/enterprisetroubleshooting.md b/docs/pingcastle/4.0/enterprisetroubleshooting.md index 76e6c65f14..280eb5fe06 100644 --- a/docs/pingcastle/4.0/enterprisetroubleshooting.md +++ b/docs/pingcastle/4.0/enterprisetroubleshooting.md @@ -54,6 +54,18 @@ Before pasting file contents into any online JSON validator, redact passwords, c Only restart the PingCastle Enterprise application pool or service after the file passes validation. +### Collecting Installer Logs + +If the installer fails or exits unexpectedly, generate a verbose installer log to diagnose the issue or attach to a support case. + +Run the installer with the `/l*v` flag and a log file path: + +``` +pingcastle-enterprise-installer.exe /l*v C:\path\to\install.log +``` + +Include this log file when opening a support case for installation issues. + ### Common Errors and Solutions Here are common errors, their causes, and how to fix them. From e382511a869443b50f5739d127f66bbc1deddb35 Mon Sep 17 00:00:00 2001 From: Joe Dibley Date: Thu, 13 Aug 2026 09:02:08 -0700 Subject: [PATCH 2/3] Document known upgrade issue: installer misdetects install directory The 4.0 installer sometimes fails to detect the existing installation directory during an in-place upgrade. Documents the INSTALLFOLDER command-line workaround. Co-Authored-By: Claude Sonnet 5 --- docs/pingcastle/4.0/enterpriseupgrade.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/pingcastle/4.0/enterpriseupgrade.md b/docs/pingcastle/4.0/enterpriseupgrade.md index fa2e31ed92..ed3b9eba0a 100644 --- a/docs/pingcastle/4.0/enterpriseupgrade.md +++ b/docs/pingcastle/4.0/enterpriseupgrade.md @@ -26,6 +26,16 @@ Test the upgrade in a non-production environment first if one is available. This PingCastle Enterprise 4.0 replaces the MSI-based installer with a single installer executable, `PingCastleEnterpriseInstaller.exe`. Upgrading from 3.5.1 to 4.0 is an in-place upgrade: you run the new installer on top of your existing 3.5.1 installation, and it detects and upgrades that installation automatically. The installer also detects and applies any prerequisite changes 4.0 requires, such as the correct ASP.NET Hosting Bundle version, so you don't need to update prerequisites manually. +:::warning Known Issue +In this release, the installer sometimes fails to detect the existing installation directory during an upgrade. If this happens, run the installer from the command line and specify the installation directory with the `INSTALLFOLDER` parameter: + +``` +pingcastle-enterprise-installer.exe INSTALLFOLDER="D:\PingCastleEnterprise\" /l*v upgrade.log +``` + +Replace `D:\PingCastleEnterprise\` with your actual installation directory. +::: + To upgrade PingCastle Enterprise from 3.5.1 to 4.0: 1. Download `PingCastleEnterpriseInstaller.exe` for version 4.0. From 21f0f0956957c13124d33dbb6bdd4d40afc0794f Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 16:06:41 +0000 Subject: [PATCH 3/3] fix(vale): auto-fix style issues (Vale + Dale) --- docs/pingcastle/4.0/enterpriseinstall.md | 8 ++++---- docs/pingcastle/4.0/enterprisetroubleshooting.md | 4 ++-- docs/pingcastle/4.0/enterpriseupgrade.md | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/pingcastle/4.0/enterpriseinstall.md b/docs/pingcastle/4.0/enterpriseinstall.md index d1dc3b792c..923b724cf5 100644 --- a/docs/pingcastle/4.0/enterpriseinstall.md +++ b/docs/pingcastle/4.0/enterpriseinstall.md @@ -69,7 +69,7 @@ The installer wizard walks you through prerequisite checks, licensing, and confi ::: :::tip Remote SQL Server Setup - If you're configuring a remote SQL Server (not on the local machine), see the [Remote Database Configuration](#remote-database-configuration) section for detailed setup instructions including SQL Authentication and Windows Authentication options. + If you're configuring a remote SQL Server (not on the local machine), see the [Remote Database Configuration](#remote-database-configuration) section for setup instructions covering SQL Authentication and Windows Authentication. ::: 7. **Authentication method**: enable **Windows Authentication**, **OpenID Connect**, **SAML2**, or a combination, and optionally disable local password login. See [Authentication](enterpriseauthsetup.md#authentication) for full configuration details for each method. @@ -136,7 +136,7 @@ Having trouble installing? See [Collecting Installer Logs](/docs/pingcastle/4.0/ 1. Run PingCastleEnterpriseInstaller.exe. The installer checks for IIS and the ASP.NET 10.0 Hosting Bundle and offers to install them if they're missing. :::warning - Installing missing prerequisites can require a server restart. If prompted, restart the server and run the installer again to continue. + Installing missing prerequisites can require a server restart. If the installer prompts you to restart, restart the server and run the installer again to continue. ::: 2. Accept the license agreement and enter your license key. @@ -152,7 +152,7 @@ For a detailed description of each wizard screen, see the Production Installatio ::: :::tip Remote SQL Server Setup -If you're configuring a remote SQL Server instead of using the local instance, see the [Remote Database Configuration](#remote-database-configuration) section for detailed setup instructions including SQL Authentication and Windows Authentication options. +If you're configuring a remote SQL Server instead of using the local instance, see the [Remote Database Configuration](#remote-database-configuration) section for setup instructions covering SQL Authentication and Windows Authentication. ::: @@ -170,7 +170,7 @@ PingCastle Enterprise requires a database user account with database owner permi ### SQL Server Permissions -When connecting to an existing database, the account PingCastle Enterprise uses requires database owner permissions. If PingCastle Enterprise runs under the IIS application pool's Windows account, grant permissions with the following SQL: +When you connect to an existing database, the account PingCastle Enterprise uses requires database owner permissions. If PingCastle Enterprise runs under the IIS application pool's Windows account, grant permissions with the following SQL: ```sql IF NOT EXISTS (SELECT loginname FROM master.dbo.syslogins diff --git a/docs/pingcastle/4.0/enterprisetroubleshooting.md b/docs/pingcastle/4.0/enterprisetroubleshooting.md index 280eb5fe06..8806e5ff71 100644 --- a/docs/pingcastle/4.0/enterprisetroubleshooting.md +++ b/docs/pingcastle/4.0/enterprisetroubleshooting.md @@ -7,7 +7,7 @@ sidebar_label: Troubleshooting ### Viewing Application Logs and Errors -When troubleshooting issues with PingCastle Enterprise, you need to view error messages and logs to diagnose problems. +To diagnose problems with PingCastle Enterprise, view its error messages and logs. Configure logging from the web portal at **Configuration** > **Settings** > **Logging**: @@ -133,7 +133,7 @@ You can find more detailed error messages in the event log or by running the app - Invalid license key - Missing or misconfigured application settings -- Runtime dependencies not installed +- Missing runtime dependencies **Solution:** diff --git a/docs/pingcastle/4.0/enterpriseupgrade.md b/docs/pingcastle/4.0/enterpriseupgrade.md index ed3b9eba0a..4d4a8297eb 100644 --- a/docs/pingcastle/4.0/enterpriseupgrade.md +++ b/docs/pingcastle/4.0/enterpriseupgrade.md @@ -44,7 +44,7 @@ To upgrade PingCastle Enterprise from 3.5.1 to 4.0: ![A screenshot of the installer installing the required ASP.NET Hosting Bundle version as part of the upgrade.](/images/pingcastle/enterpriseupgrade/prereq-install.webp) - The installer bundles the required prerequisites, including the ASP.NET Hosting Bundle, directly. The upgrade doesn't need web access to download them. + The installer bundles the required prerequisites directly, including the ASP.NET Hosting Bundle. The upgrade doesn't need web access to download them. ## Configuration migration