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

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

After you complete your profile, you’ll see three options. Select “Create a starter application”.

Name your application
Provide your AWS account ID or GCP project ID
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. Connect your cloud

In the next step you’ll give our Coherence managed service account 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

5. Create coherence.yml

The coherence.yml file tells Coherence which services 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.

You’ll add a new coherence.yml file to the root of your repository in your integration branch. Check out the coherence.yml page for documentation and examples.

6. 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 give you a hosted Cloud IDE with a clone of your repo we call Config Checker. It checks:

Docker file(s) exist
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
The config checker is still in development, and some cases of environment variables or other infrastructure requirements may not work as expected. Ask us for help if you run into any issues.

7. Configure infrastructure

Once you click the configure button on the last step, Coherence creates the resources defined in the coherence.yml file. You’ll be redirected to the dashboard UI with a modal titled “Almost done!” 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: