[![SurePassID](logo_sp_banner.jpg)](https://surepassid.com)

# InstallationManager - User Guide

## Overview

The **InstallationManager** is a Windows desktop application that helps you manage and update your SurePassID Authentication Server installation. This guide will walk you through each operation step-by-step.

## Getting Started

### Launching the Application

1. Locate `InstallationManager.exe` in your SurePassID installation folder
2. **Right-click** the file and select **"Run as administrator"**
3. The application window will open

**Important**: The application requires administrator privileges to modify system files and configurations.

### Understanding the Interface

When you launch the application, you'll see:

- **Menu Bar**: Contains Operations, View, and Help menus
- **Current Installation Folder**: Shows the production folder being managed
- **Selected Operation**: Displays which operation is currently selected
- **Preview Mode Checkbox**: Lets you see changes before applying them
- **Log Window**: Shows real-time progress and messages
- **Start Button**: Begins the selected operation
- **Copy Log Button**: Copies log messages to clipboard
- **Cancel/Done Button**: Closes the application

## Operation Types

The InstallationManager supports four main operations:

### 1. Upgrade Current Installation (In-Place Upgrade)
Upgrades your existing installation to a new version

### 2. Sync web.config to New Installation
Copies configuration from one installation to another

### 3. Install Maintenance Release
Applies updates and patches to your current installation

### 4. Rotate System Encryption Keys
Updates encryption keys for enhanced security

---

## Step-by-Step Instructions

### Operation 1: Upgrade Current Installation (In-Place Upgrade)

Use this when you want to upgrade your SurePassID installation to a newer version.

#### What It Does
- Backs up your current installation
- Updates all application files
- Migrates your configuration to the new version
- Upgrades the database if needed

#### Before You Begin
? **Backup your database** (critical!)  
? Schedule downtime with users  
? Download the upgrade package  
? Extract the upgrade files to a folder  

#### Step-by-Step Process

**Step 1: Select the Operation**
1. Click **Operations** menu ? **Upgrade current installation**
2. A checkmark appears next to the selected operation

**Step 2: Specify Folders**
1. In the **Current Installation Folder** field:
   - Click the **Browse** button (folder icon)
   - Navigate to your SurePassID production folder
   - Example: `C:\Program Files\SurePassID Corp\SurePassID Authentication Server\MfaServer`
   - Click **OK**

**Step 3: Enable Preview Mode (Recommended)**
1. Check the **Preview Mode** checkbox
2. This lets you see what will change without actually changing it

**Step 4: Start the Upgrade**
1. Click the **Start** button
2. The upgrade dialog will appear

**Step 5: Specify Upgrade Package**
1. In the upgrade dialog, click **Browse**
2. Navigate to the folder containing your upgrade files
3. Example: `C:\Temp\SurePassID_Upgrade_2025.4`
4. Click **OK**
5. Click **Continue** to proceed

**Step 6: Review Preview (If Enabled)**
1. Review the log messages showing what will be changed
2. Look for any warnings or errors
3. If everything looks good, run again with Preview Mode unchecked

**Step 7: Perform Actual Upgrade**
1. Uncheck **Preview Mode**
2. Click **Start** again
3. Click **Continue** in the dialog
4. Wait for the upgrade to complete
5. Watch the log window for progress

**Step 8: Verify Success**
1. Look for "Operation completed successfully" message
2. Click **Copy Log** to save the log
3. Click **Done** to close the application

#### After the Upgrade
- Restart IIS or the application service
- Test user authentication
- Verify all features work correctly
- Keep the backup until you confirm everything works

---

### Operation 2: Sync web.config to New Installation

Use this when you're setting up a new installation and want to copy settings from your existing one.

#### What It Does
- Copies configuration settings from one installation to another
- Preserves destination-specific settings
- Does not modify binaries or the database

#### Before You Begin
? Have both installations ready  
? Current (source) installation should be working  
? New (target) installation should be installed but not configured  

#### Step-by-Step Process

**Step 1: Select the Operation**
1. Click **Operations** menu ? **Sync web.config to new installation**
2. A checkmark appears next to the selected operation

**Step 2: Specify Source Folder**
1. In the **Current Installation Folder** field:
   - Click the **Browse** button
   - Select your existing production folder
   - Example: `C:\Program Files\SurePassID Corp\SurePassID Authentication Server\MfaServer`

**Step 3: Specify Target Folder**
1. In the **New Installation Folder** field (this field becomes visible):
   - Click the **Browse** button
   - Select your new installation folder
   - Example: `D:\SurePassID_New\MfaServer`

**Step 4: Start the Synchronization**
1. Click the **Start** button
2. Wait for the process to complete
3. Watch the log for any warnings or errors

**Step 5: Verify**
1. Look for success message
2. Click **Copy Log** to save the log
3. Click **Done**

#### After Synchronization
- Review the new installation's web.config
- Test the new installation
- Verify database connectivity
- Check that all services work properly

---

### Operation 3: Install Maintenance Release

Use this to apply patches, bug fixes, or minor updates to your current installation.

#### What It Does
- Backs up current binaries
- Replaces application files with updated versions
- Preserves all configuration settings
- Does not change the database

#### Before You Begin
? Download the maintenance release package  
? Can be a ZIP file or extracted folder  
? Review the maintenance release notes  

#### Step-by-Step Process

**Step 1: Select the Operation**
1. Click **Operations** menu ? **Install maintenance release**
2. A checkmark appears next to the selected operation

**Step 2: Specify Production Folder**
1. In the **Current Installation Folder** field:
   - Click the **Browse** button
   - Select your production folder
   - Example: `C:\Program Files\SurePassID Corp\SurePassID Authentication Server\MfaServer`

**Step 3: Start the Process**
1. Click the **Start** button
2. The maintenance release dialog will appear

**Step 4: Select Package Type**
1. You'll be asked: "Do you want to select a ZIP file?"
   - Click **Yes** for ZIP file
   - Click **No** for folder

**Step 5a: If You Chose ZIP File**
1. Browse to the maintenance release ZIP file
2. Example: `C:\Downloads\SurePassID_MR_2025.4.1.zip`
3. Click **Open**

**Step 5b: If You Chose Folder**
1. Browse to the extracted maintenance release folder
2. The folder must contain a "Server Update" subfolder
3. Example: `C:\Temp\SurePassID_MR\`
4. Click **OK**

**Step 6: Review and Confirm**
1. The tool validates the package
2. If valid, it proceeds with the update
3. Watch the log window for progress

**Step 7: Complete**
1. Wait for "Operation completed successfully"
2. Click **Copy Log** to save the log
3. Click **Done**

#### After Maintenance Release
- Restart the application/IIS
- Test key functionality
- Verify version numbers updated
- Monitor for any issues

---

### Operation 4: Rotate System Encryption Keys

Use this to enhance security by rotating the encryption keys used to protect sensitive data.

#### What It Does
- Generates new encryption keys
- Re-encrypts all encrypted data in the database
- Updates configuration files with new keys
- Maintains data integrity throughout

#### Before You Begin
?? **CRITICAL**: This operation modifies encrypted data in your database

? **Create a full database backup** (mandatory!)  
? Verify backup is valid  
? Schedule extended downtime (30-60 minutes for large databases)  
? Ensure no users are logged in  
? Stop all application services  

#### Step-by-Step Process

**Step 1: Prepare the System**
1. Notify all users of downtime
2. Stop IIS or application services
3. Create and verify database backup
4. Document current system state

**Step 2: Select the Operation**
1. Click **Operations** menu ? **Rotate system encryption keys**
2. A checkmark appears next to the selected operation

**Step 3: Specify Production Folder**
1. In the **Current Installation Folder** field:
   - Click the **Browse** button
   - Select your production folder
   - Click **OK**

**Step 4: Start Key Rotation**
1. Click the **Start** button
2. The key rotation wizard will launch

**Step 5: Confirm Database Backup**
1. The wizard will ask if you have backed up the database
2. Type **YES** to confirm (must be uppercase)
3. If you haven't backed up, type **Q** to quit and create backup first

**Step 6: Confirm Key Rotation**
1. You'll be asked to confirm you want to proceed
2. Type **ROTATE** to continue (must be uppercase)
3. The operation will begin

**Step 7: Monitor Progress**
1. Watch the log window carefully
2. Progress messages will appear as data is re-encrypted
3. This may take 30-60 minutes for large databases
4. **Do not interrupt the process**

**Step 8: Verify Completion**
1. Wait for "Key rotation completed successfully" message
2. Click **Copy Log** and save it
3. Click **Done**

**Step 9: Post-Rotation Tasks**
1. Restart application services
2. Test user authentication
3. Verify encrypted data is accessible
4. Keep database backup for at least 30 days

#### If Something Goes Wrong
?? **IMPORTANT**: If key rotation fails:
1. Review the log for error messages
2. **Do not** restart the application
3. Contact SurePassID support immediately
4. Have your database backup ready for potential restore

---

## Using the Configuration Viewer

The Configuration Viewer lets you inspect your current settings.

### Opening the Configuration Viewer

1. Click **View** menu ? **Configuration**
2. The Configuration Viewer window opens

### What You'll See

The viewer displays:
- **Connection Strings**: Database connection information (passwords hidden)
- **Key Vault**: Azure Key Vault references
- **SMTP Settings**: Email notification configuration
- **Twilio Settings**: SMS/Voice configuration
- **Service URLs**: API and service endpoints
- **Other Settings**: Additional configuration values

### Using the Viewer

1. Scroll through the list to find settings
2. Settings are displayed in a tree view
3. Sensitive values like passwords are shown as "********"
4. Copy any values you need for troubleshooting

---

## Understanding Preview Mode

Preview Mode is a safety feature that shows what will happen without making actual changes.

### When to Use Preview Mode

- ? Before any production upgrade
- ? When you're unsure about an operation
- ? To see what files will be modified
- ? To review configuration changes

### How Preview Mode Works

1. **Enable**: Check the **Preview Mode** checkbox before clicking Start
2. **Run**: The operation runs but **does not** write any changes
3. **Review**: Examine the log messages showing planned changes
4. **Decide**: If comfortable, run again with Preview Mode off

### What Preview Mode Shows

- Files that will be copied
- Configuration settings that will change
- Database migrations that will run
- Backup locations that will be created

### What Preview Mode Doesn't Do

- Does not create backups
- Does not modify any files
- Does not change database
- Does not write to disk

---

## Understanding the Log Window

The log window shows real-time messages during operations.

### Log Message Types

**INFO** (normal text): Regular progress messages  
**WARNING** (yellow): Non-critical issues to be aware of  
**ERROR** (red): Problems that need attention  

### Reading the Log

Each message includes:
- Timestamp
- Message type
- Description of what's happening

### Copying the Log

1. Click the **Copy Log** button
2. Open Notepad or your preferred text editor
3. Press Ctrl+V to paste
4. Save with a meaningful name
5. Keep the log file for your records

### What to Log

**Always save logs for:**
- Production upgrades
- Key rotations
- Any operation that encounters errors
- Troubleshooting sessions

---

## Troubleshooting

### Common Problems

#### "Could not find production folder"
**Problem**: The folder you selected is not a valid SurePassID installation  
**Solution**: 
- Make sure you selected the correct folder
- The folder should contain a `MfaServer` subfolder
- Check that the installation is complete

#### "Database connection failed"
**Problem**: Cannot connect to SQL Server  
**Solution**:
- Verify SQL Server is running
- Check the connection string in web.config
- Test connectivity with SQL Server Management Studio

#### "Operation failed" during file copy
**Problem**: Cannot copy files  
**Solution**:
- Run as Administrator
- Stop IIS or application services first
- Check disk space
- Verify antivirus is not blocking

#### "Invalid maintenance package"
**Problem**: The maintenance package structure is incorrect  
**Solution**:
- Verify you downloaded the correct package
- If using a folder, ensure it contains "Server Update" subfolder
- If using ZIP, try extracting it first and using the folder

### Getting Help

If you encounter issues:

1. **Copy the log** using the Copy Log button
2. **Review the log** for ERROR messages
3. **Check this guide** for solutions
4. **Consult the Admin Guide** for advanced troubleshooting
5. **Contact support** with the log file if needed

### Support Resources

- **Knowledge Base**: https://support.surepassid.com/general-support
- **Support Portal**: https://support.surepassid.com
- **Website**: https://www.surepassid.com

---

## Best Practices

### Before Any Operation

1. ? **Backup**: Always backup the database first
2. ? **Test**: Use preview mode when available
3. ? **Read**: Review release notes and documentation
4. ? **Schedule**: Plan downtime with users
5. ? **Verify**: Check prerequisites are met

### During Operations

1. ? **Watch**: Monitor the log window
2. ? **Wait**: Don't interrupt operations in progress
3. ? **Note**: Write down any warnings or errors
4. ? **Save**: Copy the log when complete

### After Operations

1. ? **Test**: Verify everything works
2. ? **Document**: Save logs and notes
3. ? **Monitor**: Watch for issues in the first 24 hours
4. ? **Backup**: Create a new backup of the upgraded system
5. ? **Retain**: Keep old backups for at least 30 days

---

## Keyboard Shortcuts

- **Alt+O**: Opens Operations menu
- **Alt+V**: Opens View menu
- **Alt+H**: Opens Help menu
- **Ctrl+C**: Copies selected text (in log window)

---

## Command Line Usage

You can launch the application with a production folder pre-selected:

```cmd
InstallationManager.exe "C:\Program Files\SurePassID Corp\SurePassID Authentication Server\MfaServer"
```

This is useful for:
- Creating shortcuts
- Scripting
- Multiple installations on one server

---

## Frequently Asked Questions

### Q: Do I need to stop the application before using this tool?
**A**: For most operations (upgrade, maintenance release, key rotation), yes. For viewing configuration, no.

### Q: Can I run multiple operations at the same time?
**A**: No, run one operation at a time.

### Q: What happens if the operation fails?
**A**: Check the log for error messages. For upgrades and maintenance releases, your backup can be used to restore.

### Q: How long does each operation take?
**A**: 
- Configuration sync: 5-10 minutes
- Maintenance release: 10-15 minutes  
- In-place upgrade: 15-30 minutes
- Key rotation: 30-60 minutes (varies with database size)

### Q: Can I cancel an operation once it starts?
**A**: Not recommended once file modifications begin. Wait for completion or failure.

### Q: Where are backups stored?
**A**: In a `Backups` folder with a timestamp, inside your installation folder.

---

## Glossary

**In-Place Upgrade**: Updating software in its current location  
**Maintenance Release**: Small updates that fix bugs or add minor features  
**Configuration Sync**: Copying settings from one installation to another  
**Key Rotation**: Changing encryption keys for security  
**Preview Mode**: Dry-run that shows changes without making them  
**Production Folder**: The folder containing your live SurePassID installation  
**Web.config**: XML file containing application configuration settings  

---

## Appendix: File Locations

### Typical Installation Paths

```
Production Installation:
C:\Program Files\SurePassID Corp\SurePassID Authentication Server\

MfaServer Folder:
C:\Program Files\SurePassID Corp\SurePassID Authentication Server\MfaServer\

Configuration File:
C:\Program Files\SurePassID Corp\SurePassID Authentication Server\MfaServer\web.config

Backup Folder:
C:\Program Files\SurePassID Corp\SurePassID Authentication Server\Backups\
```

### Azure VLE Paths

```
Production Installation:
C:\home\site\wwwroot\

Configuration File:
C:\home\site\wwwroot\web.config
```

---

**Need More Help?**

- ?? **Admin Guide**: For advanced configuration and troubleshooting
- ?? **Quick Reference**: For command reference
- ?? **Support Portal**: https://support.surepassid.com

---

**Document Version**: 1.0  
**Last Updated**: 2025-04-15  
**Product Version**: 2025.4.1  

**Copyright © 2026 SurePassID Corporation. All rights reserved.**
