This document will guide you through upgrading your Checkbox On-Premise installation from version 7 to version 8.
Important Note: This document applies to version 8.4.0 or later. If you are using an older version, please download a newer version from your customer portal.
If you are installing Checkbox for the first time, please see the Checkbox 8 - On-Premise Installation Guide instead.
Important Note We do not recommend upgrading your production environment until you have conducted extensive testing in your Checkbox test/development environment.
Requirements / Prerequisites
Please review the following BEFORE starting the upgrade process.
Current installation MUST be running Checkbox version 7
If you are currently on an older version of Checkbox, you must first patch or upgrade to version 7.73 before upgrading to version 8.
Server requirements for Checkbox 8
Before beginning the upgrade, please ensure that your server environment meets at least the minimum system requirements for Checkbox 8. Depending on the volume of survey data that you collect and the size of your surveys, you may find that you will need more powerful hardware to achieve optimal performance.
The most common cause of upgrade issues is missing modules or features, specifically the rewrite module. Please make sure to check our IIS module requirements document here for more information and links to download specific modules that are required. .
|
COMPONENT |
MINIMUM REQUIREMENTS |
|
Operating System |
64 bit versions of Windows Server 2012 R2, 2016, 2019, 2022 |
|
Web Server |
Microsoft Internet Information Server (IIS) 8.5 or higher with AT LEAST 4 GB RAM*; Important: check the IIS module requirements to make sure that you have the proper IIS components enabled on your server. |
|
Database |
Microsoft SQL Server 2012 or higher. SQL Server Express Editions also supported** |
|
Cloud Hosting |
Amazon EC2, Amazon Elastic Beanstalk, Azure Virtual Machines, Rackspace Cloud Servers. Checkbox supports virtual machine environments on Microsoft Azure and Rackspace. Checkbox does NOT support Rackspace Application hosting tools. |
|
Browser |
Microsoft Internet Explorer 11 or higher; most recent versions of Microsoft Edge, Chrome, Firefox, Safari*** |
|
Privileges |
Administrator access to Web Server and Database Server required for installation. |
|
Disk Space |
1GB for application installation and base database; Overall database size depends on the number of surveys, users, and responses. |
|
Software |
IIS Module Installation (URL Rewrite, ISAPI extensions & filters, ASP.NET 4.X and .Net Extensibility - see https://www.checkbox.com/support/technical-requirements/ fordetails) |
|
|
Checkbox supports using SMTP or Amazon Web Services SES for sending system emails, including survey invitations. |
IIS / URL Requirements
The Checkbox 8 On Premises installer provides two options for installation:
-
Option 1: A single URL and IIS web site (default / recommended)
This approach requires a single URL, e.g. https://www.yoursite.com, and then installs each of the three applications in virtual directories/folders so that the end result is that you have https://www.yoursite.com/api for the API, https://www.yoursite.com/admin for the Checkbox admin app, and https://www.yoursite.com/surveys for the site used to take surveys.
-
Option 2: Four URLs and four IIS web sites
This approach requires three unique / valid URLs. Each Checkbox site is configured with the application in the root of the URL. This approach is generally useful for scenarios where you'd like to install each Checkbox app on a different server or have more granular control over the settings or amount of system resources used by each application.
URL Shortener
At this time the URL shortener is a feature that is only utilized by the SMS feature of Checkbox. If you are not using this feature then the URL shortener will not be used. Note that we are hoping to expand what features of Checkbox use the URL shortener over time, so you should still ensure that the URL you assign to the shortener is valid.
SSL
We highly recommend that you use SSL on your Checkbox sites. Note that you cannot use SSL on just some of the web sites -- it is all or nothing.
Valid License File
Obtain a valid Checkbox 8 license file (.lic file). For trial customers, there is a 30 day license included in the trial download. For licensed Checkbox customers, please download a Checkbox 8 license from your customer portal.
Upgrade Instructions
Step 1: Stop Checkbox 7 and related services (if applicable)
If you are upgrading a production environment or database that is being actively used by Checkbox 7, you must stop these web sites AND the Checkbox Messaging Service prior to starting the upgrade process.
Once upgraded, you cannot run your old installation or its messaging service against the upgraded databases. It is important that you do not restart the Checkbox 7 site or service unless you are reverting due to an error with the upgrade.
Failing to do either of these will result in data corruption or loss and Checkbox Support may not be able to assist with recovery. Backup (see step 2) is essential!
Step 2. Backup your Checkbox databases.
This is a crucial step. If any errors or issues arise from this upgrade you will need to immediately revert the upgrade.
Backup your Checkbox database using a "Full" SQL backup. If you use a separate database for the Checkbox Messaging Service, you should back this up as well.
Please consult the Microsoft SQL Server documentation or talk to your database or IT administrator to perform this step.
Step 3: Unzip the Checkbox download files
Unzip the files into a temporary location. If possible this should not be the final location of the application.
IMPORTANT NOTE: The installer will copy the files to a location of your choice.
Step 4: Install the license files
You will need to place your Checkbox 7 license file (.lic) in both the Checkbox\api-core folder and Checkbox\checkbox-service-core folders in the temporary location specified in step 2. Please do this before running the installer.
Step 5. Run the Checkbox Installer to configure your installation and upgrade your database
You should perform this step on the server that you wish to install Checkbox on. Run the .exe file named “Checkbox-Installer.exe” in the root of the Checkbox 8 zip file. This application will request important settings information about your installation that will be used to configure the web applications and service for you.
This step requires the following information:
-
The URLs that you will use for Checkbox.
These should be valid domain names that are already configured / have DNS entries that resolve to the server you are installing on. If you’d like to use SSL (and have a valid SSL certificate installed), you may use HTTPs. - Database connection information
You should have the database hostname, username, password, and database name for both the core Checkbox database and the Messaging database. - SMTP or Amazon SES credentials
This is required in order for Checkbox to send emails.
When you run the installer make sure to choose the "Upgrade" option to upgrade your Checkbox v7 database.
The Checkbox 8 installer will upgrade your database in its last step. Once this completes without error, you can move on to the next step.
At this time, we recommend that you select "disabled" for Active Directory even if you intend to use it. It must be configured manually until we can complete overhaul (see step 8).
Please note: Windows Management Framework 4.0 is required to run the installer. If your system does not have it installed, you can install it from http://www.microsoft.com/en-us/download/details.aspx?id=40855
Step 6: (Optional) Enable Write Permission for the Logging Folder
By default, Checkbox writes error log files to the local disk in API-Core\App_Data\Logs (if these folders don't exist, please create them).
You will need to give the Application Pool user write permission to this folder for this functionality to work correctly. Follow the "Default Logging Configuration / Installation Step" in the Configuring Error Logging instructions.
You can complete this step later if you'd like.
Step 7: (Optional) Add reCAPTCHA keys
If you'd like to use the reCAPTCHA survey item (used to stop spam survey responses), you'll need to follow the reCAPTCHA configuration instructions. Note that this step can be completed at a later time if you'd like.
Step 8: (Optional) Set up Active Directory (LDAP)
Moving from Checkbox 7 to Checkbox 8, we have made significant changes to our Active Directory support to allow it to function in more environments. Due to this, the configuration requirements have changed and the installer currently has not been expanded to handle the additional requirements.
After installation, modify the ldap.json file, located in api-core\Configs and checkbox-service-core\Configs by following the instructions on Checkbox 8 LDAP configuration.
After modifications are complete, restart the checkbox service and the IIS site.
Please share your experience and LDAP configuration with us so we can continue to improve this functionality.
Step 9: Confirm that the Checkbox Admin app login page is available.
Once the sites have been configured in the previous step, the application should be available. You will want to navigate to your [AppURL]/login page. You should see a login page asking for a username and password.
You can now log into Checkbox using the same admin credentials as Checkbox 7.
Check your configuration - the installer attempts to migrate configuration settings from Checkbox 7 to 8, but it may not have correctly captured all settings. Your old settings are still in the Checkbox 7 configuration files. Please share your experience with us so we can correct these issues as they show up.
Step 10: (Optional) Remove Checkbox 7 Files
Once the upgrade is complete and you can access Checkbox 8 you can remove the application files for Checkbox 7 and the Checkbox Service files from your web server. In your Checkbox installation, these folders are Checkbox 7:
api
app-admin
app-take-survey
checkbox-service
url-shortener
You will notice that each of these folders has a complementary folder with "core" added to the name, like api and api-core. The "core" folders are Checkbox 8. Aidditionally, the "root" folder should be left intact.
You may wish to leave your Checkbox 7 files, especially configuration, intact for some time before eventually removing them.
IIS:
If you do not have other applications in your CheckboxSurveys-v7 and CheckboxSurveys-v7-shortener app pools, you may delete them.
0 Comments