What is required to migrate my app?

Any application that serves web traffic and is either a static application or can be containerized is deployable on Coherence. A greenfield app can be live in as few as 15 minutes (most of that is waiting for cloud resources to provision). An existing app running homegrown infra-as-code tools typically takes a few hours of work before it is fully migrated. We're happy to help with migrations! Just shoot us a note at support@withcoherence.com.

In general, our approach is incremental and our goal is to get your application running as quickly as possible in a new, parallel set of non-production infra as quickly as possible. We then want you to take the time to build confidence and experience with what we've set up and make sure it works for your team and application, before moving over any critical workloads such as production.

There are 3 components to getting your app live on Coherence.

• GitHub and cloud integration installations
• defining coherence.yml for your application
• making sure your app is cloud-ready

GitHub and Cloud Integration

After registering your user and team on Coherence, you'll install our GitHub app in your repos, and grant a Coherence-controlled service account a role in your cloud account.

• See more details on what these steps look like for AWS and GCP
  • For each application, Coherence requires your production and non-production workloads to live in separate projects (GCP) or accounts (AWS).
  • Multiple Coherence apps can share the same account, for example multiple applications can deploy to a one staging/dev account. The account you onboard when setting up a new Coherence app will be used for non-production workloads.
  • For AWS, we recommend making sure that you have an account structure with an Organization and child accounts. This does not incur extra costs, will scale with you as you grow, and will enable you to manage consolidated billing and IAM permissions across accounts. It will also position you to use AWS IAM Identity Center most effectively when you're ready to do so.
    • We are happy to spend some time with you reviewing your account setup before starting a migration, feel free to reach out and book a call!
  • If your app depends on Git LFS support, you don't need to do anything special, we will support it out of the box!
• Read about the security and privacy considerations at play here

Defining coherence.yml

The coherence.yml file tells Coherence which services and infrastructure your application needs, across different environments such as development, staging, PR previews, and production. This includes defining the databases, redis instances, private workers (e.g. celery or sidekiq), scheduled tasks (aka CronJobs), build process, tests, and compilation information.

• The dev and prod commands are defined to tell Coherence what commands to run in your container in either a Workspace Cloud IDE, or a deployed environment, like a preview environment or your production environment.
  • If your framework requires you to collect static assets, like in Rails or Django, make sure to include that command here!
• For AWS apps, valid database versions are major or minor strings, but do not include the -R1 at the end of the description in the console. For example, 14 or 14.1 are valid, but 14.1-R1 is not.

During our onboarding flow, we will give you access to a hosted Cloud IDE with a clone of your repo, where you can use our Config Checker to make sure that you have a valid coherence.yml and that it defines all the resources your app will need.

For information on defining multiple services, either in one or multiple repos, and for special considerations like how URL routing across services will work, see more info here.

Getting Cloud-Ready

The term "cloud-ready" is hard to define. With the right infrastructure, any app can be deployed in the cloud. That said, there are a few key references that define what "cloud-ready" means for Coherence. Similar to 12 factor apps, Coherence wants your application to be built, packaged, configured, and monitored in a standardized fashion. Many of the same principles apply (though that was really written for deployments to Heroku). These requirements are in place so that your application can be deployed in as secure, scalable, and reliable a manner as possible.

The 3 most important steps in getting cloud-ready for Coherence are:

• containerization
• application configuration
• platform configuration

Containerization

Each service of your application will be containerized for at least some part of its lifecycle. That means it will need its own Dockerfile or it will be built using Nixpacks if a Dockerfile is not provided.

• Services with type frontend only use the container for the build process (e.g. TS-to-JS). Static assets that result are served via a CDN when deployed.
• backend services use containers for CI/CD tasks such as tests/database seeding/database migrations, as well as for running the application when deployed.
• Containers must be linux/unix based (we do not support Windows). We make every effort to support minimal containers such as alpine. The minimum requirements are that your container has sh and sleep available and present on the default path of the ENTRYPOINT of the container.

Various overrides are provided for using different containers at different points in the SDLC via coherence.yml for example using a different container for compiling, testing, or for development vs. staging/branch previews/production. Please see the yml docs for details.

Application Configuration

Application configuration is the process of making sure that your application is looking at the right place for configuration information, for example:

• making sure database connection info is acquired from $DATABASE_URL, or similarly cache info from $REDIS_URL
• configuring the app server to listen to 0.0.0.0:$PORT
• having a passing health check endpoint in the container (this must return a 200 - a redirect such as a 301 or 302 will not be accepted). Please check trailing slashes or other small changes in the URL - these often result in a redirect and "work locally" but are not treated as passing by the AWS health check.
  • on AWS, the HOST header of the health check will be set to the internal IP of the ALB making the request, which is not known ahead of time and cannot be determined from the ECS task itself. Therefore, if your app checks the HOST of the request, it must allow all hosts, or at least any host from an IP of 10.0.0.0, for the health check path.
  • the COHERENCE_ENVIRONMENT_DOMAIN variable can be used for other ALLOWED_HOSTS type checks or CORS checks in your application
• if the domain name is used in the app, for example in routing to subdomains, making sure that it is not hard-coded and is using $COHERENCE_ENVIRONMENT_DOMAIN

Platform Configuration

In this step, you ensure that all required configuration for your application is present in the Coherence platform, for example making sure that all required environment variables are set in our UI, and that the coherence-generated service role for the application deployment has the necessary IAM configuration in your cloud provider, for example if you wanted to use it to access services that Coherence does not yet manage.