If you have decided to migrate ArcGIS Enterprise with WebGISDR, you can use the workflows provided on this page as a starting point to help guide your migration. The scenarios behind each workflow may not entirely match your organization's, as they are intended to give general steps for common deployment scenarios.
Migrate a single-machine deployment
If you are migrating a single-machine base deployment, you can use the same name between the new and old environments using the \etc\hosts file. There are two common patterns with single machine deployments:
- The fully qualified domain name of the machine matches the host in the URL used to access the deployment.
- The fully qualified domain name of the machine does not match the host in the URL used to access the deployment. Users access the deployment through an alias or CNAME record.
How you add entries into the \etc\hosts file differs depending on your environment.
Migrate when the machine host name matches the organization URL
In this scenario, ArcGIS Enterprise is installed on a machine called enterprise.domain.com and is running on Windows Server 2016. The host name of the machine matches the host name of the organization URL.
Members access ArcGIS Enterprise in the following ways:
Organization members access:
- Content and items: https://enterprise.domain.com/portal
- Service endpoints: https://enterprise.domain.com/server/rest
Organization administrators and publishers access:
- ArcGIS Server Manager: https://enterprise.domain.com:6443/arcgis/manager
- ArcGIS Portal Administrator Directory: https://enterprise.domain.com:7443/arcgis/portaladmin
- ArcGIS Portal Directory: https://enterprise.domain.com:7443/arcgis/sharing/rest
To migrate this type of environment, use the following steps:
- Enable read-only mode in your existing deployment.
- Acquire your new machine.
This can be a virtual machine or physical machine.
In this example, the machine's host name is enterprise1.domain.com, its IP address is 10.0.0.2, and it's running Windows Server 2022.
- On the new machine, update \etc\hosts file to resolve the IP address of the new machine to enterprise.domain.com:
10.0.0.2 enterprise.domain.com
The \etc\hosts file must be updated before you install any software on the new machine.
- Repeat step 3 on any other machine you might use to test and validate the new system.
Note:
This does not include the existing production machine.
- Install and configure ArcGIS Enterprise components.
Once the environment is configured, you can only reach the new environment through the enterprise.domain.com host name from the machine itself or from any other machine that you've added the entry to. Any machines without the entry will resolve enterprise.domain.com to your original production environment through DNS.
- Create a backup using the WebGISDR tool.
It is important to consider timing when creating a backup. Once you create a backup using the WebGISDR tool, only the content present in the deployment will be moved over. If you did not enable read-only mode during step 1, this is especially important to consider. It's recommended that you run a backup during a period of downtime to prevent the loss of any new content.
- Restore the backup on the new machine with the WebGISDR tool.
This will create a replica of the existing deployment on the new machine.
- Validate that users, content, groups, and services are accessible on the new machine, using any machine on which you've added the \etc\hosts entry.
Only machines with the 10.0.0.2 enterprise.domain.com entry in the hosts file will resolve enterprise.domain.com to the new machine. Otherwise, those requests will go to the original machine.
- Once the environment has been validated and you're ready to switch over, update DNS to resolve enterprise.domain.com to the new machine.
All requests to enterprise.domain.com will now resolve to the new machine, including all content from the old environment.
- Remove the 10.0.0.2 enterprise.domain.com entry from the \etc\hosts file on the new machine and on any other machine to which you added it.
Migrate when ArcGIS Enterprise is accessed through an alias
In this scenario, ArcGIS Enterprise is installed on a machine called machinename.domain.local and is running on a Windows Server 2016 operating system. Your DNS stores a CNAME, or alias, for the machine as enterprise.domain.com.
Members access ArcGIS Enterprise in the following ways:
Organization members access:
- Content and items: https://enterprise.domain.com/portal
- Service endpoints: https://enterprise.domain.com/server/rest
Organization administrators and publishers access:
- ArcGIS Server Manager: https://machinename.domain.local:6443/arcgis/manager
- ArcGIS Portal Administrator Directory: https://machinename.domain.com:7443/arcgis/portaladmin
- ArcGIS Portal Directory: https://machinename.domain.com:7443/sharing/rest
To migrate to this type of environment, use the following steps:
- Enable read-only mode in your existing deployment.
- Acquire your new machine.
This can be a virtual machine or physical machine.
In this example, the machine's host name is newmachine.domain.local, its IP 10.0.0.2, and it's running Windows Server 2022.
- On the new machine, update the \etc\hosts file to resolve the IP address of the new machine to newmachine.domain.local as well as enterprise.domain.com:
10.0.0.2 newmachine.domain.local enterprise.domain.com
The \etc\hosts file must be updated before you install any software on the new machine.
Listing the local host name into the \etc\hosts file first ensures that the software will store the name in configuration files, rather than the DNS alias. Adding the DNS alias ensures the deployment can be configured with the DNS alias without impacting production.
- Repeat step 3 on any other machine you will use to test and validate the new system.
Note:
This does not include the existing production machine.
- Install and configure ArcGIS Enterprise components. Use the DNS alias when registering the Web Adaptor.
Once the environment is configured, you can only reach the new environment through the enterprise.domain.com host name from the machine itself or from any other machine that you've added the entry to. Any machines without the entry will resolve enterprise.domain.com to your original production environment through DNS.
- Create a backup using the WebGISDR tool.
It is important to consider timing when creating a backup. Once you create a backup using the WebGISDR tool, only the content present in the deployment will be moved over. If you did not enable read-only mode during step 1, this is especially important to consider. It's recommended that you run a backup during a period of downtime to prevent the loss of any new content.
- Restore the backup on the new machine with the WebGISDR tool.
This will create a replica of the existing deployment on the new machine.
- Validate that users, content, groups, and services are accessible on the new machine, using any machine on which you have added the \etc\hosts entry.
Only machines with the 10.0.0.2 enterprise.domain.com entry in the hosts file will resolve enterprise.domain.com to the new machine. Otherwise, those requests will go to the original machine.
- Once the environment has been validated and you're ready to switch over, update the DNS to resolve enterprise.domain.com to the new machine.
All requests to enterprise.domain.com will now resolve to the new machine, including all content from the old environment.
- Remove the 10.0.0.2 enterprise.domain.com entry from the \etc\hosts file on the new machine and on any other machine to which you added it.
Migrate a multi-machine deployment
If you have a distributed environment, you must modify the \etc\hosts file to ensure that the component acting as the front end for your deployment (its instances of ArcGIS Web Adaptor or reverse proxy) is resolving to the original name.
In this scenario, ArcGIS Enterprise components are distributed across two machines; both running a Windows 2016 operating system:
- Two instances of ArcGIS Web Adaptor are installed on a machine called enterprise.domain.com
- Portal for ArcGIS, ArcGIS Server, and ArcGIS Data Store are installed on a machine called m1.domain.com
The objective for this scenario is to migrate to a newer operating system, for example: Windows Sever 2022.
Members access ArcGIS Enterprise in the following ways:
Organization members access:
- Content and items: https://enterprise.domain.com/portal
- Service endpoints: https://enterprise.domain.com/server/rest
Organization administrators and publishers access:
- ArcGIS Server Manager: https://m1.domain.local:6443/arcgis/manager
- ArcGIS Portal Administrator Directory: https://m1.domain.com:7443/arcgis/portaladmin
- ArcGIS Portal Directory: https://m1.domain.com:7443/arcgis/sharing/rest
To migrate an environment with this scenario, do the following:
- Enable read-only mode in your existing deployment.
- Acquire two new machines, one to host instances of ArcGIS Web Adaptor and the other to run the rest of the components.
The only IP address that matters in this case is the Web Adaptor machine, because the only settings that must match between deployments are the https://enterprise.domain.com/portal and https://enterprise.domain.com/server. The IP address of the new Web Adaptor machine in this example is 10.0.0.2.
- On each new machine, update the \etc\hosts file to resolve the IP address of the Web Adaptor machine to enterprise.domain.com:
10.0.0.2 enterprise.domain.com
- Install the two ArcGIS Web Adaptor instances on enterprise1.domain.com.
- Install Portal for ArcGIS, ArcGIS Server, and ArcGIS Data Store on m2.domain.com
- Create the portal and server sites.
- Register the Data Store to the server site.
- Configure the instances of ArcGIS Web Adaptor on enterprise1.domain.com by reaching the configuration page through https://enterprise.domain.com/portal/webadaptor and https://enterprise/domain.com/server/webadaptor.
The requests will be resolved to the new Web Adaptor machine (which is actually enterprise1.domain.com) through the \etc\hosts file.
- Federate your server site with the portal, and ensure that you use https://enterprise.domain.com/server as the services URL.
The admin URL can be either https://enterprise.domain.com/server or https://m2.esri.com:6443/arcgis.
- Create a backup using the WebGISDR tool.
It is important to consider timing when creating a backup. Once you create a backup using the WebGISDR tool, only the content present in the deployment will be moved over. If you were unable to enable read-only mode during step 1, this is especially important to consider. It's recommended that you run a backup during a period of downtime to prevent the loss of any new content.
- Restore the backup on the new machine with the WebGISDR tool.
This will create a replica of the existing deployment on the new machine.
- Validate that users, content, groups, and services are accessible on the new machine, using any machine on which you have added the \etc\hosts entry.
Only machines with the 10.0.0.2 enterprise.domain.com entry in the hosts file will resolve enterprise.domain.com to the new machine. Otherwise, those requests will go to the primary machine.
- Once the environment has been validated and you're ready to switch over, update DNS to resolve enterprise.domain.com to the new machine hosting the Web Adaptor and remove the \etc\hosts entry on that machine as well as on m2.domain.com.
All requests to enterprise.domain.com will now resolve to the new machine, which will direct traffic to m2.domain.com. There, you will be able to work with all the content from your old environment on your new machines.
Migrate a cloud deployment
If you use ArcGIS Enterprise Cloud Builder for Microsoft Azure or AWS CloudFormation templates to create your environments, you don't have the opportunity to modify \etc\hosts entries before installing and configuring the software. Therefore, it's necessary to use new URLs for the deployment.
Once the environment is created, you can update the public URLs of the new organization to match the existing production environment. The internal URLs (privatePortalURL and the admin URL used for federating) will still point to the new DNS name, allowing internal traffic to continue going to the correct location. When you run the WebGISDR tool, it will overwrite all content in the target environment with the correct URLs, completing the migration.
In this scenario, the existing production environment uses the following URLs:
- Organization URL: https://enterprise.public.com/portal
- Services URLs: https://enterprise.public.com/server
- Enable read-only mode in your existing deployment.
- Create a new environment with different URLs.
This scenario uses the following URLs:
- Organization URL: https://enterprise-new.public.com/portal
- Services URLs: https://enterprise-new.public.com/server
- Update the organization URL to point to https://enterprise.public.com/portal.
- Update the services URL to point to https://enterprise.public.com/server.
- Create a backup using the WebGISDR tool.
It is important to consider timing when creating a backup. Once you create a backup using the WebGISDR tool, only the content present in the deployment will be moved over. If you were unable to enable read-only mode during step 1, this is especially important to consider. It's recommended that you run a backup during a period of downtime to prevent the loss of any new content.
- Restore the backup in the new environment with the WebGISDR tool.
This will create a replica of the existing deployment in the new environment.