Server Host Recovery Guide

This guide is intended to assist a Server administrator with recovering a Server instance in the event of failure of an original host or hosts, when moving to a new upgraded Server, moving from an on-premises to a cloud server, and in other cases where your infrastructure changes. 

In Scope

• Recovery from the failure of a single, default Server installation using embedded MongoDB.
• Available backup with necessary information intact.
• The target machine(s) can be overwritten.

Out of Scope

• Multi-node Server environment or user-managed MongoDB - please contact customer support for help.
• Merging of databases of connection files.
• Back up or restoration of ODBC drivers.
• Back up or restoration of User or system DSNs.
• Back up or restoration of other aliases stored in Windows that exist outside of Alteryx.

Part 1. Stand Up a New Server

1. Install Server on the target server. Ensure it is the same version as the original Server.
2. Open Command Prompt > Run as administrator. You must be an administrator on the target server for this option to be available.
   
3. Stop the Alteryx Service on the target server if it is running. Verify the service has stopped before proceeding with further steps.
   Command: net stop alteryxservice
4. Navigate to the Alteryx installation directory (Default: %ProgramFiles%\Alteryx\bin).
   Command: cd %ProgramFiles%\Alteryx\bin
5. Copy the RuntimeSettings.xml from the original machine to the target machine directory (%PROGRAMDATA%\Alteryx). Overwrite any current file if it exists.
   Note: Make sure to copy the RuntimeSettings.xml file from the original machine. Do not cut and paste it, as it will be needed in its original state in step 10.
   • (Optional) If a RuntimeSettings.xml file currently exists in the %PROGRAMDATA%\Alteryx folder, make a copy before overwriting the file.
6. Edit the copied RuntimeSettings.xml, now in the %PROGRAMDATA%\Alteryx folder. Remove the <ServerSecretEncrypted> value under the <Controller> section and save.
7. Set the Controller token to the value from the original Server. 
   Note: Running this command will update the <StorageKeysEncrypted> value in the RuntimeSettings.xml file on the target machine. 
   Command: AlteryxService.exe setserversecret={ControllerTokenValue}
8. (Optional) If you had a Run-As User set in Server System Settings on the original Server, execute the following command to set the Run-As user and password.
   Command: AlteryxService.exe setexecuteuser=name,domain,password
9. (Optional) If the Gallery is enabled and you had an SMTP server set with a specific password in Server System Settings on the original machine, execute the following command to set the SMTP password.  This should be done even if you are not planning to use SMTP or it is disabled.
   Command: AlteryxService.exe setsmtppassword=password
10. Replace the <StorageKeysEncrypted>{value}</StorageKeysEncrypted> in the RuntimeSettings.xml file on the target machine (%ProgramData%\Alteryx\RuntimeSettings.xml) with the value from the same field in the RuntimeSettings.xml file from the original machine.
    Note: The <StorageKeysEncrypted> values in the two RuntimeSettings.xml files should be different at the beginning of this step.  If you find they are the same, confirm you set the controller token from the original machine (step 6 above), then get the <StorageKeysEncrypted> value from the RuntimeSettings.xml file located on the original machine.
    

 

Part 2. Restore the MongoDB Database

The restored MongoDB database on the new Server will likely reference the old Server hostname, causing issues with Gallery indexing. Failure to perform the steps below will prevent users from seeing newly published workflows or other changes to the Gallery.

1. Restore the MongoDB backup to an empty folder on the target Server. Record the target location of the restore for use in later steps.

   This command needs to be run from %ProgramFiles%/Alteryx/bin (default path).  

   Command:  AlteryxService.exe emongorestore=<path to backup location>,<path to restore to>
   Example:  AlteryxService.exe emongorestore="D:\MongoBackups\2019-08-26”,”D:\ProgramData\Alteryx\Service\Persistence\MongoDB_Restore”

    

2. Start up the MongoDB database. Leave this window open.
   Command: mongod ––dbpath <path to restored database> ––auth ––port 27018
   Example: mongod ––dbpath ”D:\ProgramData\Alteryx\Service\Persistence\MongoDB_Restore” ––auth ––port 27018
3. Replace the <EmbeddedMongoDBRootPath>{Path}</EmbeddedMongoDBRootPath> in the RuntimeSettings.xml file (%ProgramData%\Alteryx\RuntimeSettings.xml) with the target location.
   
4. Open a second Administrative command prompt, change directories to the Server installation path (Default: %ProgramFiles%\Alteryx\bin).
   Command: cd %ProgramFiles%\Alteryx\bin
5. In the second command prompt, retrieve the MongoDB connection password:
   Command: AlteryxService.exe getemongopassword
6. In the second command prompt, connect to the MongoDB database using the command and connection string below. 
   Command: mongo mongodb://{server}:{port}/{galleryDatabase} -u user -p {Non-Admin Password}
   Example: mongo mongodb://localhost:27018/AlteryxGallery -u user -p CCEC********************************33C0
   
7. In the second command prompt, remove the records from the locks collection in the AlteryxGallery database.
   Command: db.locks.remove({})
   • After executing the command, you should see a result similar to “writeResult({ “nRemoved” : N })”, where N is a number between 0 and 2.
     
8. In the second command prompt, enter the following command to exit the MongoDB shell.
   Command: exit
9. In the first command prompt, stop the MongoDB database.
   Command: Ctrl+c
10. Close both command prompts.
    Command: exit
11. Open Designer on the new machine and activate the license(s) if necessary. Close Designer.
12. Open Server System Settings and step through each page in the System Settings. Confirm all settings are set as intended, including: check Base Address for Gallery, verify the Controller Token, any passwords set for settings such as the Run-As user, and SMTP password. After confirming the settings, select Finish to start the AlteryxService.
13. Confirm that the Service started.
    
14. (Optional) Restore the system-wide Alteryx and In-DB Connection alias files as described in the requirements. Restore to the same locations as listed in requirements. 
15. (Optional) Restore the user-based Alteryx and In-DB Connection alias files described in the requirements. Restore to the same locations as listed in requirements. 

The host recovery process is now complete. Follow the steps below to confirm that your host recovery was successful.

 

Part 3. Confirm Host Recovery

We recommend you perform a Gallery indexing test and a test of Gallery workflow credentials to determine that your host is successfully recovered. 

Gallery Indexing Test

Start by verifying a newly uploaded workflow appears. To do so, follow the steps below.

1. Open Designer on a client machine.
2. Create a workflow. Unless you wish to test specific database connections or functionality, your test workflow can be as simple as a Text Input. Database testing is outside the scope of this guide.
3. Select File > Save As in Designer, then choose the appropriate Gallery connection of the new deployment.
   • If the new Gallery doesn't appear in the list, select Add a Gallery, and follow the instructions to log in.
4. Save the workflow with a unique name that you will be able to identify to verify the test is successful.
5. Enter the Gallery URL directly in a web browser. Sign in with the same Gallery account that you used to save the workflow.
   • Note: Do not use the View In Browser button shown after saving – this will not adequately test the functionality.
6. Select Private Studio and look for the workflow you just uploaded. 
   • If you are unable to locate the workflow, try the following:
     1. Search for the unique name of the workflow you uploaded in the search bar at the top of the page.
     2. Try sorting the view by Latest to see if the workflow appears.
     3. Confirm you have completed all the steps process above, specifically the restoration of the MongoDB Database.
     4. Contact Alteryx Customer Support for help.

Test Gallery Workflow Credentials

Testing steps for Gallery workflow credentials will depend on the Credentials setting within the Gallery Admin panel. 

To access the Gallery Admin interface, select your username in the upper-right corner of the Gallery and choose Admin from the drop-down. Select Credentials on the left side of the page. Follow the steps below based on the setting Credentials setting for workflows.

If the Credentials setting for workflows is Use Default Credentials and there are no credentials displayed on the page, no verification is necessary.

If the Credentials setting for workflows is Use Default Credentials and there are credentials displayed, you might have a Subscription/Studio that uses a default credential option.

1. To test, have a user with access to this studio verify that the workflow(s) execute. Note that even though a credential might not be shared directly with a studio, it can still be set as a default. If the workflow test errors, reach out to Alteryx Customer Support for help.

If the Credentials setting for workflows is Require User Credentials, one or all the below scenarios might apply. 

1. You might have a Subscription/Studio that uses a default credential option.
   • To test, have a user from one of these studios verify that the workflow(s) execute. Note that even though a credential might not be shared with a studio, it can still be set as a default. If the workflow test errors, reach out to Alteryx Customer Support for help.
2. You might have one or more user(s) who saved the credentials upon workflow execution via the Make these my default credentials option.
   • To test, have the user execute a workflow with default credentials and confirm the workflow runs. If the workflow test errors, reach out to Alteryx Customer Support for help.
3. You might have users that have access to workflow credentials.
   • To test, confirm users can execute workflows with at least one credential created before the host recovery procedure. If the workflow test errors, reach out to Alteryx Customer Support for help.

If the Credentials setting for workflows is Allow users to select credentials, confirm all test scenarios as described above. Reach out to Alteryx Customer Support for help if any workflow tests error.