Planning your Upsun migration: the 6-9 week roadmap

We’ve seen migrations take a week. We’ve seen them take three years. Here’s why 6-9 weeks is the sweet spot. You’ve signed with Upsun. You’re excited about the infrastructure-as-code approach, the preview environments, and the developer experience. There’s just one small thing standing between you and all that goodness: the migration. If you’re a technical lead or manager responsible for planning this transition, you’re probably asking yourself: How long will this take? What could go wrong? And more importantly, how do we avoid those things that could go wrong? I sat down with Lucas Stil, Senior Manager of Onboarding & Migration at Upsun, to answer exactly these questions. Lucas has guided hundreds of migrations over the years, from the well-planned to the “developer’s leaving for a kayak trip on Saturday, we need to go live Thursday” variety. Here’s what he’s learned.

​

The timeline question

Let’s start with the obvious: How long does a migration actually take? Lucas: We generally suggest 6 to 9 weeks. That’s our ideal timeline, and there’s a reason for it. You can break it down nicely: 2 weeks for building and configuration, 2 weeks for testing, and 2 weeks for preparation and go-live. Now, is that timeline set in stone? No. Recently, we had a client who had a single developer, and that developer was leaving on vacation on Saturday. Their old hosting was ending. So we got it done in a week, went live on Thursday so the developer could be available Friday, and then he went off to kayak in the middle of nowhere with no phone service for two weeks. But do we recommend that? Absolutely not. What makes 6-9 weeks work better than, say, doing it in a week or spreading it over a year? Lucas: The 6-9 week timeline gives you room to test properly, room to iterate when things don’t work the first time (and they won’t, that’s normal), and room to turn around if you need to adjust something. It’s not so long that you’re dealing with a moving target where people are developing new features in parallel and you’re trying to migrate and keep up with changes on the old system at the same time. The migrations that take years? Those are usually because the team is trying to do the migration alongside regular feature development. You don’t have someone whose job is to migrate. You have someone who’s also got tickets in their sprint, and they’re trying to juggle both. That’s when it drags out.

​

Phase 1: Understanding Your Infrastructure (Week 1-2)

Before you write a single line of configuration or touch any deployment settings, you need to take a photograph of what you have now. Not what you think you have. Not what the infrastructure might theoretically handle on your worst Black Friday ever. What you actually have, right now, running in production. Lucas on why this matters:

“We’ve had clients tell us ‘Oh yeah, I forgot to mention: my MariaDB runs on a dedicated machine with 8GB of RAM.’ That changes everything. You need to know these things before you start planning, not discover them halfway through the migration.”

Yes, Upsun makes it easy to scale up later. But that’s not the point. The point is avoiding surprises. When you know what you have upfront, you can size things correctly from day one and skip the “why is our bill so high?” conversation later.

​

Your infrastructure photography checklist

Start by documenting everything. Here’s what you need to capture:

• Services inventory: Every service your application currently uses (databases, search engines, message queues, cache layers, etc.)
• Current resource allocations: How much CPU, memory, and storage each service actually uses under normal load
• Custom configurations: Any non-default settings, especially for databases (think custom MariaDB configurations for Magento, for example)
• Dependencies map: Which services depend on which other services
• External connections: Any third-party services you connect to that care about IP addresses (and some do). You’re switching infrastructure, which means new IPs, which means updating allowlists before migration day
• File storage patterns: How many files, in what structure, and whether they’re organized or all dumped in one directory

A word on sizing: Here’s a trap that catches a lot of people. Lucas explains:

“Clients often fall into this pattern: they look at their worst day ever, the day when traffic went crazy and everything was stressed to the limit, and they say ‘let’s provision for that.’ And then they’re disappointed because yes, it’s very performant, but it’s also very expensive. Unless Black Friday is your daily reality, you don’t need to size for peak. Size for a normal day plus 10-15%. That’s a good target.”

​

Creating your configuration files

Once you know what you’re working with, you need to translate that into Upsun configuration. You have a few tools to help:

1. Templates: Check if there’s an official template for your stack (Drupal, WordPress, Symfony, etc.). These are well-maintained and give you a solid starting point.
2. config.upsun.com: This tool can connect to your repository and generate configuration for you. It’s not perfect (you’ll need to review and adjust), but it works well as a first pass.
3. Documentation: When in doubt, the Upsun docs are your friend. You’re defining infrastructure as code, which means you’re writing .upsun/config.yaml files. Take the time to understand the structure.

The goal at the end of this phase: you should have configuration files that represent your current setup, even if they’re not optimized yet.

​

Phase 2: Get an MVP Running (Week 3-4)

Here’s where many migrations get their first real test. Before you worry about copying production data, before you stress about load testing, before you do anything else: get a minimal version of your application working on Upsun. Lucas on the importance of the MVP:

“This is critical. Even if you’re missing static resources, even if you don’t have the full database, even if workers or email sending isn’t configured yet: get the site running. If you can log into your admin interface and click around, move an article or two, that’s your MVP. This step determines the velocity of everything that comes after.”

​

What “working” means

Your MVP doesn’t need to be perfect. It needs to prove that:

• Your application code deploys correctly
• The basic services (web server, primary database) are configured properly
• You can access the application
• The fundamental structure is sound

Missing pieces at this stage are fine:

• Background workers
• Mail sending
• Full production data
• Static assets
• Advanced features

​

Getting familiar with the tools

If you’re new to Upsun, this is where you’ll start learning the CLI and SSH access. These aren’t just for migration; they’re how you’ll interact with your environments going forward. Lucas notes:

“There’s a learning curve here. The Upsun CLI, SSH access to your environments: you’ll need these during migration, especially for file copying. But if you already know the platform, this becomes a non-issue.”

Think of this as optional-but-recommended time. The more comfortable you are with the tooling now, the smoother migration day will be.

​

Phase 3: Load Testing with Production Data (Week 5-6)

This is the phase that many clients skip, and according to Lucas, that’s a mistake. This is where you find the problems that matter, not in theory but in practice. Lucas on why load testing is essential:

“Clients often don’t take the time to do this, and that’s unfortunate. You need to import all the production resources: the full database, all the static files, everything. Then you run a load test. Not sized for your worst day ever, but for a normal day plus 10-15%.”

​

Setting up your test environment

Before you can test, you need production-like conditions:

1. Import the full production database: Not a subset. Not sample data. The whole thing.
2. Copy all static assets: Every image, every PDF, every uploaded file. Use rsync (we’ll talk about file organization in a moment).
3. Configure all services: Even if you’re not testing them specifically, having Redis, Elasticsearch, or whatever else you use in place means you’re testing the real setup.

​

The read-only filesystem trap

Lucas explains the scenario:

“On Upsun, the filesystem is read-only by default. So if clients test lightly with a few users, everything seems fine. But then they haven’t realized their file-based cache is disabled because they don’t have Redis configured, and there’s no cache at all. When you test alone, it works great. Then you run a load test and it falls apart.”

You want problems to show up during the load test, not after you go live. If you discover that your caching strategy doesn’t work with a read-only filesystem, this is the time to find out.

​

What to monitor during load tests

While your tests are running, keep an eye on:

• Metrics in the Upsun console: Watch for bottlenecks at the container or service level
• Blackfire: Use it to identify performance issues in your application code
• Response times: Are they comparable to your current setup?
• Error rates: Any 500s, 502s, or other failures under load?

Lucas on iteration:

“You’ll iterate here. That’s expected. Maybe you didn’t size something right, maybe there’s a configuration issue like the cache example. That’s the point of this phase: find those issues and fix them before they’re production problems.”

​

Generating load test scenarios

Here’s the annoying part about load testing: writing realistic test scenarios. You need scripts that actually mimic what users do, not theoretical perfect paths through your application. This is where tools like Claude Code come in handy. Instead of hand-crafting k6 or Locust scripts, you describe what users actually do (“browse catalog, add to cart, check out” or “search products, filter, view details”), and Claude Code writes the test code for you. If you’re curious how this works in practice, we’ve got a detailed walkthrough on generating load test scenarios with Claude Code.

​

The file organization problem

Here’s a real-world example that affects migration speed. Lucas shared this story: Lucas on file organization:

“We had a client with all their files in one folder. No organization, no structure. PDFs, images, everything from multiple contributors, all in one directory. I think it was 15,000 to 20,000 files in a single folder. And that takes time to process, even with rsync doing differential copies. Even though there were few changes, rsync still had to count and verify every file, and that’s slow.”

The solution? Create a directory structure before migration if you can:

• By file type (images, documents, etc.)
• By date or category
• Using a hash-based structure (first two characters of SHA-256 hash as folder, next two as subfolder)

The hash-based approach is cleanest if you have a lot of files. It’s a bit of work to set up initially, but it makes finding files programmatically easy and keeps rsync fast.

​

Common pitfalls and how to avoid them

Let’s talk about the patterns that cause problems, based on Lucas’s experience with dozens of migrations.

​

Pitfall 1: The Moving Target

The problem: You’re migrating to Upsun while simultaneously developing new features on your old platform. Now you’re trying to keep two systems in sync, test features on both sides, and everything takes twice as long. Lucas’s take:

“The moving target is what makes migrations drag out. You test a feature on the new infrastructure, but you also need to push it to the old system, and maybe it doesn’t work quite right on the old system so you have to adjust. You’re running in circles.”

The solution: Dedicate resources. Have someone whose job during these 6-9 weeks is the migration, not someone who also has a sprint full of feature tickets.

​

Pitfall 2: Skipping the Load Test

The problem: Everything works fine with you clicking around the site, so you figure you’re good to go. Lucas’s warning:

“If you skip load testing, you’re gambling. Sure, the site loads. But does it load under your normal traffic? Does it handle concurrent users? Does your checkout flow work when 50 people are buying things simultaneously? You don’t know until you test.”

The solution: Make load testing with production data a non-negotiable part of the plan.

​

Pitfall 3: Discovering Infrastructure Details Too Late

The problem: You’re deep into the migration when you discover “oh, by the way, our Redis setup is custom” or “did we mention the database has some special configuration?” Lucas’s advice:

“This is why we start with the infrastructure photograph. Get it all written down before you start. Special configurations, custom setups, anything that’s not default—document it first.”

The solution: The checklist from Phase 1 is your insurance policy. Do it thoroughly.

​

Your pre-migration checklist

By the end of your 6-9 weeks, before you even think about scheduling migration day, here’s what should be in place:

​

Configuration and setup

• Complete infrastructure documentation (services, sizes, configurations)
• .upsun/config.yaml created and tested
• MVP deployed and validated on Upsun
• All required services configured (databases, cache, search, queues)
• Environment variables and secrets configured

​

Testing and validation

• Full production database imported and tested
• All static assets copied to Upsun
• Load testing completed with production-scale data
• Performance metrics comparable to current setup
• Any discovered issues resolved or understood

​

Preparation for migration day

• File replication strategy defined (rsync with differential copies)
• Database replication set up (if supported for your database)
• DNS/CDN strategy determined (TTL reduction or backend switch)
• Maintenance page ready (both CDN and application-level if needed)
• Team trained on Upsun CLI and SSH access
• Rollback procedure documented (even if you don’t plan to use it)

​

Timeline and communication

• Migration day scheduled
• Team availability confirmed
• Stakeholders notified of timeline
• User communication plan prepared

​

What’s next

You’ve got your plan. You’ve tested everything. Your team knows the platform. Now it’s time for the actual migration day. In the next article, we’ll walk through the cutover process itself: maintenance windows, the sequence of operations, verification steps, and what to do in those first critical 24 hours after you flip the switch.