On-Premises Additional Instances | Axero Documentation

Introduction

This guide walks you through duplicating your Axero site from one environment to another, such as copying a production site to a sandbox or staging environment. This process also applies when migrating your site to a new domain (e.g., changing from my.oldcompany.com to my.newcompany.com).

Table of Contents

• Introduction
• Prerequisites
• Prepare for Migration
• Copy Site Files and Database
• Configure the Target Environment
• Update Database Records
• Update SSO Configuration
• Finalize the Installation
• Troubleshooting
• Support and Feedback
• Related pages

Prerequisites

Before you begin, ensure the following are in place:

• The target environment is set up according to the On-Premises Installation Guide guide.
• You have administrative access to IIS Manager on the target server.
• You have administrative access to SQL Server on the target server.
• You have a license key for the new site. Contact your Client Success Manager if you do not have one.

Prepare for Migration

If your site uses Single Sign-On (SSO), change the login method to SSO Login + Communifire Login before proceeding. This ensures you can still sign in with a username and password if SSO is temporarily unavailable during the migration.

1. Navigate to Control Panel > System > Single Sign On.
2. Select SSO Login + Communifire Login.
3. Click Save.

Copy Site Files and Database

1. On the source server, zip the site files from the directory where your site is installed (e.g., D:\websites\intranet.com).
2. Transfer the zip file to the target server.
3. On the source server, create a backup of your SQL database and zip the backup file.
   
4. Transfer the database backup to the target server.

Configure the Target Environment

Stop the Application Pool and Site

1. On the target server, open IIS Manager.
2. Stop the application pool and site for the target environment.
   

Prepare the Site Folder

1. Unzip the site files on the target server.
2. Delete the following configuration files from the unzipped copy to prevent overwriting the target site settings:
   • CFAppSettings.config
   • CFAppSettings-Overrides.config
   • CFConnectionStrings.config
   • CFProviders.config
   • CFSSOSettings.config (if present)
   • saml.config (if present)
   • web.config
   • WindowsADSettings.config
3. Copy the remaining files to the target site folder. When prompted, select Replace the files in the destination.

Set Folder Permissions

1. In File Explorer, right-click your site folder and select Properties.
2. Go to the Security tab and click Edit.
3. Click Add, enter IIS AppPool\<YourAppPoolName>, and click OK.
4. Select Read permission only and click OK.
5. Assign additional permissions to the application pool identity:
   • Assets folder: Right-click the folder, select Properties > Security > Edit, select the application pool identity, and set Modify permission.
   • bin/HiQPdf.dep file: Right-click the file, select Properties > Security > Edit, select the application pool identity, and set Read and Execute permission.

Restore the Database

1. Open SQL Server Management Studio on the target server.
2. Right-click Databases and select Restore Database.
3. Select Device, click the browse button, and locate the database backup file. Click OK.
   
   
4. After the restore completes, right-click the restored database and select Properties.
5. On the Options tab, set the compatibility level to SQL Server 2016 (130).
6. Click OK.

Create the Database User

1. In SQL Server Management Studio, expand the server's Security node, right-click Logins, and select New Login.
2. Select SQL Server authentication and enter a login name and password. Ensure there are no trailing spaces.
3. Uncheck Enforce password policy.
4. Go to the User Mapping page, select the restored database, and assign the db_owner role.
5. Click OK.
6. Verify the user was created correctly:
   1. Expand your database and navigate to Security > Users.
   2. Right-click the new user and select Properties.
   3. On the Membership page, confirm that db_owner is assigned.
   4. On the Owned Schemas page, confirm that db_owner is selected.
   5. Click OK.
7. Open the CFConnectionStrings.config file on the target server and update the connection string to point to the new database and the user you just created. Save the file.

Update Database Records

Update the Unique ID

Each Axero installation requires a unique identifier. Run the following SQL query against the target database to generate a new one:

DECLARE @Guid UNIQUEIDENTIFIER;
SET @Guid = LOWER(NEWID());

UPDATE Dyve_Dynamic_Property
SET PropertyValue = @Guid
WHERE PropertyName = 'UniqueID';

UPDATE Dyve_Tenant
SET UniqueID = @Guid;

Update the Site URL

Run the following SQL query to update all internal references from the old domain to the new domain. Replace <NEW DOMAIN URL> with the URL of your target site and <OLD DOMAIN URL> with the URL of the site you are copying:

DECLARE @NewDomain NVARCHAR(200) = '<NEW DOMAIN URL>'
UPDATE Dyve_Content
SET ContentBody = REPLACE(ContentBody, '<OLD DOMAIN URL>', @NewDomain)
WHERE ContentBody like '%<OLD DOMAIN URL>%'

UPDATE Dyve_PB_Widget
SET WidgetProperties = REPLACE(WidgetProperties, '<OLD DOMAIN URL>', @NewDomain)
WHERE WidgetProperties like '%<OLD DOMAIN URL>%'

UPDATE Dyve_UrlMapper
SET OldUrl = REPLACE(OldUrl, '<OLD DOMAIN URL>', @NewDomain),
NewUrl = REPLACE(NewUrl, '<OLD DOMAIN URL>', @NewDomain)

UPDATE Dyve_Media_Server
SET MediaServerRootURL = REPLACE(MediaServerRootURL, '<OLD DOMAIN URL>', @NewDomain)
WHERE MediaServerRootURL like '%<OLD DOMAIN URL>%'

Update Elasticsearch Configuration

Elasticsearch connection settings are stored in the database. When you restore a production database, these settings still point to the source environment. Run the following SQL queries to update them:

-- Update Elasticsearch Server URL
UPDATE [Dyve_Dynamic_Property]
SET [PropertyValue] = 'http://your-elasticsearch-server:9200'
WHERE [PropertyName] = 'ElasticsearchServer';

-- Update Elasticsearch Username
UPDATE [Dyve_Dynamic_Property]
SET [PropertyValue] = 'your_elasticsearch_username'
WHERE [PropertyName] = 'ElasticsearchUsername';

-- Update Elasticsearch Password
UPDATE [Dyve_Dynamic_Property]
SET [PropertyValue] = 'your_elasticsearch_password'
WHERE [PropertyName] = 'ElasticsearchPassword';

-- Update the CA fingerprint, only needed when Elasticsearch serves https
UPDATE [Dyve_Dynamic_Property] SET [PropertyValue] = 'your_ca_fingerprint' WHERE [PropertyName] = 'ElasticsearchCAFingerprint';

Replace the placeholder values with the Elasticsearch credentials for your target environment. If Elasticsearch is installed on the same server, the server URL is typically https://localhost:9200.

Update the HTTP Redirect Rule (If Applicable)

If your new site does not have SSL enabled, open the web.config file and comment out the HTTPS redirect rule to prevent redirect loops:

<!--
  <rule name="HTTP to HTTPS redirect" stopProcessing="true">
    <match url="(.*)" />
    <conditions>
      <add input="{HTTPS}" pattern="off" ignoreCase="true" />
      <add input="{HTTP_X_FORWARDED_PROTO}" pattern="^https$" negate="true" ignoreCase="true" />
    </conditions>
    <action type="Redirect" redirectType="Permanent" url="https://{HTTP_HOST}/{R:1}" />
  </rule>
-->

Update SSO Configuration

If your site uses SAML-based Single Sign-On (e.g., Microsoft Entra ID / Azure AD), update your identity provider to recognize the new domain. Skip this section if your site does not use SSO.

Update Microsoft Entra ID (Azure AD)

1. Sign in to the Microsoft Entra admin center with an account that has at least the Cloud Application Administrator role.
2. Navigate to Microsoft Entra ID > Enterprise applications.
3. Select the application configured for your Axero site.
4. Go to Single sign-on and click Edit on the Basic SAML Configuration section.
5. In the Identifier (Entity ID) field, update the URL to your new domain (e.g., https://my.newcompany.com).
6. In the Reply URL (Assertion Consumer Service URL) field, update the URL to your new domain followed by /SAML/AssertionConsumerService.aspx (e.g., https://my.newcompany.com/SAML/AssertionConsumerService.aspx).
7. Click Save.

Finalize the Installation

1. Run iisreset from an elevated command prompt on the target server. This clears cached settings and ensures the application loads with the updated database values.
2. Start the application pool and site in IIS Manager. The site may take a few minutes to load on the first request.
3. Update the license:
   1. When the site loads, click Click here to manage your license.
   2. Sign in to the site and click Click here to manage your license again.
   3. Click the Add Domain button.
      
   4. Add your new HTTP domain and license key.
   5. If your new site has SSL enabled, also add the HTTPS domain with the license key.
4. Disable email sending:
   1. Navigate to Control Panel > System > General Settings > Email Settings.
   2. Uncheck Enable email sending.
   3. Click Save System Settings.
5. Update SSO settings:
   • For test or staging environments: Navigate to Control Panel > System > Single Sign On, click Disable SSO, and click Save. This prevents the staging site from interfering with your production SSO configuration.
   • For production domain migrations: If you completed the Update SSO Configuration section, SSO should remain enabled. Verify that you can sign in through your identity provider with the new domain.
6. Rebuild the search index: Follow steps 7 and 8 in the How to Install Elasticsearch guide to rebuild the Elasticsearch index for the new environment.

Troubleshooting

If the site displays an error after starting, enable detailed error messages to diagnose the issue:

1. Open the web.config file in the site folder.
2. Locate the customErrors element and set the mode to Off:

   <customErrors mode="Off" defaultRedirect="Errors-CF/default.aspx" redirectMode="ResponseRewrite">

   Copy
3. Save the file and refresh the site in your browser to see the full error details.

Site Times Out Behind Cloudflare or a Reverse Proxy

If your site is behind Cloudflare or another reverse proxy and you receive a 524 timeout error, the proxy can reach your server but the application is not responding in time. To diagnose:

1. In your DNS provider (e.g., Cloudflare), temporarily set the site's DNS record to DNS Only (disable the proxy) and reload the site.
   • If the site loads or shows a .NET error, the issue is the proxy timing out during a slow startup. Keep the proxy disabled until the site is stable.
   • If the site still times out, the issue is within IIS or the Axero application. Continue with the steps below.
2. On the web server, open a browser and navigate to https://localhost (or add a hosts file entry for your domain pointing to 127.0.0.1).
   • If the site loads locally, the issue is external (DNS, proxy, or network).
   • If it fails locally, check the IIS application pool, the SQL connection string, and the Elasticsearch configuration.
3. Open Event Viewer > Windows Logs > Application and look for recent .NET Runtime or ASP.NET errors. Messages such as "Cannot open database" or "Invalid license" indicate the specific misconfiguration.

Support and Feedback

We are always working to improve our documentation. If you encounter an issue not covered here, or if a step could be clearer, let us know through a Support Case so we can help you and improve this guide for everyone.

Related pages

• On-Premises Installation Guide (to set up the target server before copying the site onto it)
• How to Install Elasticsearch (to give the copy its own Elasticsearch)
• Self-Hosted Site Management Guide (why production and non-production sites stay on separate servers)
• On-Premises Disaster Recovery (to plan backups of the new site)
• Managing Your Sandbox (a sandbox for a cloud-hosted site)