Migration Guide | Coherence Documentation

This guide will walk you through the requirements and steps of migrating an application to Coherence. We're happy to help with migration if you'd like to request onboarding support.

Pre-requisites

In general, we suggest that you have familiarity with Docker (OCI) containers, your chosen cloud provider (AWS or GCP), and GitHub before starting the migration.

Containerization (Dockerfiles)
A GitHub repository
An AWS account or Google Cloud project (of which you're an admin)

Containerize your app

Each service of your application will be containerized for at least some part of its lifecycle. That means it will need its own Dockerfile. If you don’t provide a Dockerfile for your service, we’ll attempt to build it with Nixpacks.

frontend services use the container for the build process (e.g. TS-to-JS or minification). The resulting static assets are served via a CDN when deployed.
backend services use containers for build pipeline tasks such as tests, database seeding/migrations, and running the application when deployed.
Containers must be linux/unix based (we do not support Windows). We support minimal containers e.g. alpine.
Containers must have sh and sleep available and present on the default path of the ENTRYPOINT of the container.

We provide various overrides for using different containers at different points in the SDLC e.g. using a different container for compiling, testing, or for development vs. staging/branch previews/production. Please see the coherence.yml docs for details.

GitHub repository

Coherence naturally supports monorepos with each service defined in coherence.yml. Services defined this way can be accessed through a load balancer using different paths. This makes it easy to make changes across multiple services in a single commit.

In a multi-repo, each service is stored in a separate repository. Each has its own coherence.yml file and is deployed independently. Communication between services is done through environment variables or app logic.

Whether multi or monorepo, an app in Coherence can have only one repository associated with it. In a monorepo, you could have multiple apps using the same repo, or one app using one repo with multiple services defined

Learn more about repo structure

Cloud account / project

Coherence organizes environments by two collections called Preview (non-production) and Production. Each collection is associated with a separate cloud account or project.

For initial migration you only need to add your Preview (non-production) cloud account/project.

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 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 more effectively when you're ready to do so.

Learn more about the cloud services we configure: AWS, GCP

Go to app.withcoherence.com and create an account. The steps below walk you through our guided UI.

2. Create a new app

Name your application
Provide your GitHub repository URL

Below the GitHub URL field is the option to set your default branch. This is a different concept to your default branch in GitHub. A few things to note:

This is where you’re initially going to add and build out your coherence.yml file during the migration process
We’ll create an "integration branch" environment in Coherence automatically tracking this branch. Note that this environment cannot be deleted unless you delete your Coherence application.
If you do your migration on a temporary branch, we can change the integration branch when you’ve finished and want to merge to a permanent home

3. Install the GitHub app

The GitHub app gives Coherence repository level privileges to trigger builds and infrastructure configuration jobs based on code pushes to the repo. You can find our GitHub app here.

Each user in your app will use GitHub App OAuth to provide individual tokens to Coherence that are scoped to the same repositories that the app is installed in. These tokens are used in Workspaces and when manually submitting builds.

4. Create coherence.yml

The coherence.yml file tells Coherence what resources and infrastructure your application needs across different production and non-production environments. This includes defining the databases, redis instances, async workers (e.g. Celery or Sidekiq), scheduled tasks (aka CronJobs), build process, tests, and compilation information.

Coherence offers a "Generate" option for your configuration during onboarding, which can reduce this step to just a few seconds. Read more on our blog here.

You can choose to manage this file in your Coherence dashboard which is generally faster and easier. Alternatively, you can add a coherence.yml file to the root of your repository in your integration branch and choose "Manage in repo". Check out the coherence.yml page for documentation and examples.

5. Connect your cloud

At this point, you'll land on your application dashboard. The next step is to add your preview cloud, for which you'll see a button right there on the page. You’ll be asked to add a Coherence managed service account with the necessary IAM roles in your cloud account. This gives Coherence access to the API’s required to perform automated configuration of the cloud native services we support.

How to add the Coherence IAM role: AWS, GCP

6. Import variables

Here you can optionally import secrets/variables with a convenient .env style syntax.

7. Pass health checks

On the last step we check whether we can detect the services you’ve defined in coherence.yml before starting the initial configuration.

To check that your coherence.yml file is correctly configured, we ask you to check that:

Docker file(s) exist (or you elect to use nixpacks)
Image builds successfully
For frontend services, checks that assets are where they’re expected to be after a build
For backend services, checks that the app starts up and listens on $PORT successfully

8. Configure infrastructure

Once you click the configure button on the last step, Coherence creates the resources defined in the coherence.yml configuration. You’ll be redirected to the Infrastructure jobs tab. This step can take anywhere from 5-30 minutes depending on the complexity of the configuration. Once Coherence successfully submits a build to your integration branch, you’re up and running!

What to do next: