Migrate your app to Upsun Cloud without a rewrite

Application migrations stall for a predictable reason: the demanding part is rarely the application code itself. It is the infrastructure around it: the deployment logic, pipeline, and environment configuration that has to be rebuilt. 

That surrounding work is what turns a migration into a multi-month project, and it is why teams stay on infrastructure that no longer serves them.

Upsun Cloud reduces migration to a much smaller task. You describe your runtimes, services, and routes once, in a configuration file that lives in your repository, move your data, and test the result on a branch. The application code stays as it is.

What migrating to Upsun Cloud requires

Key takeaway: Migration is a matter of describing your existing stack in one config file, not rebuilding it. Your application code and CI tooling come with you unchanged.

Migration describes your existing setup rather than rebuilding it; the vast majority of what you already have stays in place:

• Your application code. If you are running Next.js, Django, Symfony, or another supported framework, you are not rewriting business logic to fit a new model.
• Your CI tool. If you already have one you like, it does not need to be replaced.

What you add is a single file, .upsun/config.yaml, committed to your repository like any other code. It is not entered into a separate dashboard or a vendor-specific console. The file declares three things:

• Your application runtime, the language, and the version your app runs on.
• The services your app depends on, such as a database, a cache, or a search index. There is no need for a third-party provider, but you can use one still if you want.
• How those pieces relate to each other, so the platform knows how to connect them.

Writing this file is closer to documentation than to infrastructure engineering. You are describing what your app needs, not provisioning servers by hand.

Step-by-step migration to Upsun Cloud

Key takeaway: Every step runs on an isolated branch, so you validate the whole migration against real data before production is ever affected.

After setting up your project and git repo on Upsun Cloud, the migration happens in small steps, each one able to run without requiring a maintenance window. Production stays unaffected until you choose to merge.

1. Add the config file next to your existing app in your repo. This step alone does not deploy anything. You are describing your stack, not committing to anything yet.

2. Push a branch. Pushing creates an isolated environment tied to that branch. Production is untouched. You are testing in a real, running environment, not a local approximation of one.

3. Add your environment variables. Utilize the console or CLI to add whatever variables are needed to run your application.

4. Sync data into the branch environment. Run upsun environment:synchronize code data to pull a copy of the parent environment's data into the branch. When the branch is created from production, that means you are testing against real production data, not fixtures that may not reflect actual conditions.

5. Iterate on the configuration, not the code. If something is misconfigured, the fix happens in the YAML file on that branch. Your application logic does not become part of the debugging loop.

6. Merge only when the branch is proven. Cutover happens last, after the environment has already been shown to work. There is no point in this process where you are testing in production for the first time.

Each step is reversible. If step 4 surfaces a problem, you fix it and repeat the step. Nothing downstream depends on getting an earlier step right on the first try.

The setup that stays with you

Key takeaway: The tools and habits you already rely on, git, the CLI, your language, and your services, carry over to Upsun rather than being replaced.

• Your git workflow. Push and branch the way you already do.
• Your CLI habits. Upsun Cloud is scriptable through the CLI and API, not limited to a web console.
• Your language and runtime. Next.js, Django, Symfony, and Laravel are common examples, and the platform supports a broad range beyond these, including Go, Ruby, and CMS platforms like WordPress and Drupal.
• Your existing service versions, where supported, including PostgreSQL, MySQL, and Redis.

What changes

Key takeaway: The changes are in how infrastructure is defined and secured, declared in config rather than wired by hand.

Your workflow and stack come with you, but a few things do work differently once you are on Upsun Cloud. Here is what is genuinely different.

• Services are declared: You still specify which services you need, but you do it by declaring them in the config file instead of provisioning database instances and wiring network access by hand. Once declared, the platform provisions and secures them.
• Variables are scoped to a project or a single environment. Sensitive credentials are set as project or environment-level variables through the CLI or Console, rather than committed to code or copied by hand between environments.

Try it on a branch

Migration feels risky because the validation usually happens in the wrong place. With a single cutover, the first real test of whether it worked comes after the switch, when the application is already live and serving users. This approach moves the test earlier.

You add a configuration file to your repository, push a branch, and watch your application run on Upsun Cloud against a copy of your real production data. Nothing about your live site changes while you do this. If the branch works, you have your proof, and you keep going. If it does not, you fix the config and push again, or you walk away having spent an afternoon rather than a quarter.

That is the difference an incremental path makes. You are not committing to a migration before you know whether it works. You are testing a migration, watching the result, and deciding from a position of evidence rather than hope. The cost of finding out is one branch.

Frequently asked questions (FAQs)

Do I need to rewrite my application code to migrate?   
No. Migrating to Upsun Cloud does not require changes to your application logic. The only new artifact is a configuration file that declares your runtime and services. Your code moves over unchanged.

Will testing a migration affect my live production site?   
No. Migration testing happens on a branch, in its own isolated environment. Production is untouched until you choose to merge, and by that point the environment has already been tested against a copy of production data.

How are environment variables and secrets handled when migrating to Upsun Cloud?   
Sensitive credentials are set as project or environment-level variables through the CLI or Console, rather than copied by hand between environments. A shared .env file does not need to be migrated as-is. Each variable is set at the level where it should apply, so it is scoped correctly from the start.

What happens to my existing CI/CD pipeline?   
Upsun Cloud's build and deploy process is triggered by a git push and handles provisioning automatically. A separate CI tool for linting, tests, or code review checks can keep running alongside it, so you do not need to remove your existing pipeline to test a migration.

Which frameworks and languages does Upsun support?   
Upsun Cloud supports a broad range of languages and frameworks, including Next.js, Django, Symfony, Laravel, Go, and Ruby, along with CMS platforms like WordPress and Drupal.