Getting Started
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
andprod
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
or14.1
are valid, but14.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.
Let us know if you'd like to use a different name than coherence.yml
for your application, we can configure that for you!
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 hassh
andsleep
available and present on the default path of theENTRYPOINT
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 a301
or302
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 theALB
making the request, which is not known ahead of time and cannot be determined from the ECS task itself. Therefore, if your app checks theHOST
of the request, it must allow all hosts, or at least any host from an IP of10.0.0.0
, for the health check path. - the
COHERENCE_ENVIRONMENT_DOMAIN
variable can be used for otherALLOWED_HOSTS
type checks or CORS checks in your application
- on AWS, the
- 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
This is generally the hardest and most time-consuming part of migrations to Coherence. Our team is excited to get on a call and roll our sleeves up to get you running - we've seen a lot of different applications and are able to quickly diagnose many common issues that seem elusive.
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.