Zero Downtime Migration

This guide provides step-by-step instructions for migrating your applications from Vercel, Netlify, AWS, or another provider to Sherpa.sh with zero downtime.

Caution

Zero Downtime migration only works if you have a way to loadbalancer traffic across both providers.

This guide is for websites with significant traffic that cannot schedule downtime for DNS records to propagate. Typically, most users of sherpa.sh will not need to follow this Zero-Downtime migration strategy and can just self-setup from the portal.

Any migration can still benefit from following the recommendations in DNS Migration Best Practices- such as lowering TTLs before migrations

Prerequisites

• An active Sherpa.sh account
• Access to your current hosting platform (Vercel, Netlify, AWS, etc)
• Access to your DNS provider
• Your application’s source code repository

Zero-Downtime Migration Strategy

The key to a zero-downtime migration is to set up and verify your application on Sherpa.sh before changing your DNS settings. This is accomplished through a parallel deployment strategy:

The Parallel Deployment Method

1. Deploy to Sherpa.sh while keeping your existing deployment active
2. Verify functionality using Sherpa.sh temporary URLs
3. Implement DNS changes using a phased approach
4. Monitor and finalize the migration

DNS Migration best practices

To avoid downtime during DNS propagation:

1. Lower TTL values in advance:
   • At least 24-48 hours before migration, reduce the TTL (Time To Live) values for your DNS records to the minimum allowed value (often 300 seconds/5 minutes)
   • This ensures faster propagation when you make the actual switch
2. Use Sherpa.sh’s preview environment:
   • Before changing production DNS, fully test your application on Sherpa.sh’s preview domain. Follow the getting started guide to deploy your application on a preview domain
3. Implement CNAME flattening (if supported by your DNS provider):
   • Set up CNAME records pointing to the records displayed when you setup your custom domain in the Sherpa.sh panel
   • This provides more flexibility during the transition
4. Use parallel DNS configuration:
   • Configure your application on Sherpa.sh to respond to your domain. For example, set allowed hosts to include your domain.
   • Verify your application is working on the preview domain

Migration Process

1. Connect and deploy your app on a preview domain

Follow the getting started guide to deploy your application on a preview domain

2. DNS Migration

• In your DNS provider:
  1. Use a temporary subdomain and point it with CNAMEs to the records displayed when you setup your custom domain in the Sherpa.sh panel
  2. Keep your existing DNS records active
  3. Test the Sherpa.sh deployment using the temporary subdomain. Don’t forget to add the domain to your allowed hosts or similiar setting in your application.

Note

For example, if you run your app on app.example.com the temporary domain to test could be app-temp-test.example.com. The goal is to make sure that you are able to have records in your DNS provider point successfully to an app running on Sherpa.sh before moving your primary domain.

3. Migrate Traffic

For mission-critical applications, use this blue-green deployment approach:

1. Set up complete infrastructure on Sherpa.sh (the “green” environment, like you did in step 1)
2. Keep your current platform running (the “blue” environment)
3. Use a load balancer or traffic manager to control traffic distribution. Some DNS providers will allow you to do this from DNS itself. This is the recomend way.
4. Gradually shift traffic percentages from blue to green
5. Monitor for any issues and be prepared to shift back if necessary

4. Testing

• Once you’ve traffic shifted fully to sherpa.sh, test your application.
• Keep the original deployment on your old provider active for 24-48 hours as fallback while you test the new production environment
• You can remove the old DNS records once you are confident the migration was successful.

Troubleshooting

Common Issues and Solutions

DNS Propagation Problems

• Issue: Some users see the new site while others see the old one
• Solution: This is normal during DNS propagation. Wait 24-48 hours for full propagation, and keep both deployments active during this period.

Missing Environment Variables

• Issue: Application errors related to configuration
• Solution: Verify all environment variables are correctly set in Sherpa.sh dashboard

Build Failures

• Issue: Deployment fails on Sherpa.sh
• Solution: Check build logs and adjust configuration based on differences between platforms

Database Connection Problems

• Issue: Application cannot connect to database
• Solution: Verify connection strings and network access settings. You may need to allow all IPs to access your database if you are not using a sherpa.sh managed database.

Getting Help

If you encounter issues during migration, contact Sherpa.sh support in discord:

https://discord.com/invite/Pn7N2Wwbjy