Skip to content

Migrating from Coherence v1 to v2 (Beta)

This guide will walk you through the process of migrating your application from Coherence v1 to the new v2 (Beta) version. We'll cover steps for both AWS and GCP migrations to ensure a smooth transition regardless of your cloud provider.

V1 vs V2

There are a few big differences:

  • You can use many repos as part of one app in v2
  • There are new flavors such as run-lite and lambda-lite that might be a better fit for your app and save you money
  • You can customize environment collection, environment, and service shape much more deeply. Any environment type can be in any collection, and services in any environment can track a branch if you want CI/CD behavior on git push events
  • Easier to share resources like a database across many services
  • cnc is open-source and based on docker-compose.yml, and can be customized deeply or used outside Coherence itself
  • better support for integrations with cocli and cnc CLI's
  • test and integration_test are not supported natively in v2. We recommend using external CI like this example

Pre-Migration Steps

  • Create a new app in the beta site
    • Log in to the Coherence v2 (Beta) site
    • Click "New App" and follow the prompts to create your application
  • Configure your first environment
    • Add your repositories to the new app
    • Add and configure your services as needed
  • Make environment variable changes
    • Create aliases in Coherence v2 for any changed variables you use, e.g. COHERENCE_ENVIRONMENT_DOMAIN vs. CNC_ENVIRONMENT_DOMAIN. You can do this in the Variables tab in the v2 site to match any variables your code is expecting.
  • Add cloud-specific customizations (if applicable)

Testing and Preparation

  • Test the new deployment
    • Deploy your app to a Coherence-provided URL
    • Familiarize yourself with the new toolbox feature. It is not web-hosted and depends on your local runtime. There are som install steps. We've added the proxy-only mode to make using resources like database clients easier on your local machine.
    • Add a test custom domain to test things like Auth0 or similar that might depend on the URLs, as well as CSRF and other behavior of your app during a domain change
  • Create production environment/collection
    • Set up your production environment in Coherence v2. You can follow the docs here to learn more
  • Create previews (if you use them)
    • Set up previews in your app by following along here. This replaces the Feature in v1
  • Load data into the new database
    • This won't apply if you don't use an database instance in the cloud on v1. For example if you use Neon or Supabase, you can ignore this part.
    • AWS:
      • You cannot change the VPC of an RDS instance, so you'll have to make a new copy from an RDS snapshot or other backup method
      • Export data from your v1 database or restore from a backup
      • Import this data into your new v2 database or restore to a new instance
      • You will need to take downtime and do a final migration if you accept writes into the system after the snapshot is created
      • to move your database, you have options:
        • create your new environment on Coherence v2, provision the infra, and then manually delete the instance we create and restore to a new instance of the same name. you'll need to update the secrets that manage the DATABASE_URL and DB_PASSWORD for your environment in the AWS Cloud Console (or use the same username/password as that secret provides by changing them after you restore)
        • configure your resource for the environment with the use_existing setting in your cnc.yml. See this doc for what this looks like. You provide a secret in the same format as the managed one or with the password for your instance
        • You can also use a public IP and skip the VPC setup if you prefer
    • GCP:
      • If using Cloud SQL, you can use the same instance for both v1 and v2 during migration
        • You can use a public IP from the v2 system until you are ready to switch networks fully, and can configure the appropriate connection info in v2 as a manually as a secret in Coherence after you switch the network to the v2-managed VPC

Migration

  • Switch custom domain
    • Set up your custom domain in the new v2 production environment
    • Update your DNS settings
    • Wait for DNS propagation (this can take up to 48 hours, but is often much quicker)
  • Test new production environment
    • Thoroughly test your application in the new v2 production environment
    • Ensure all features are working as expected
  • Decommission v1 infrastructure
    • Once you're confident everything is working in v2, and users are no longer using it, begin the process of spinning down your v1 infrastructure

Post-Migration

After completing the migration:

  • Monitor your application closely for the first few days
  • Keep your v1 infrastructure around for a short period, in case you need to quickly revert
  • Update any CI/CD pipelines or other integrations to work with your new v2 setup. See the cocli docs for more
  • Familiarize yourself with new v2 features and optimizations for your cloud provider. There are a lot more architecture and customization options now!

Remember, migrations can be complex processes. Don't hesitate to reach out to Coherence support if you encounter any issues or have questions during your migration. Our team is here to ensure a smooth transition from v1 to v2. We appeciate your time and consideration to make this happen.