How to migrate from OVH Web PaaS

Prepare to migrate

Before moving any code or data from your Web PaaS project, you’ll need to set up your account and download the CLI.

1. Lower the TTL of your DNS: Lowering the Time To Live of the DNS entries you want to migrate is important for the fastest migration. Access your DNS management system and adjust the TTL of each entry you’ll update. Depending on your registrar and the time to live (TTL) you set, it can take anywhere from 15 minutes to 72 hours for DNS changes to be taken into account, so it’s best to reduce this value to incur the lowest possible transition time.

2. Register: Registration will grant you access to the platform and the free trial.

   • Sign up for an Upsun account
   • Sign up for a Platform.sh account

3. Install the CLI: The migration steps will require the use of our Command Line Interface.  The installation process is described in our documentation. Follow the directions there to install and to validate that your account has been authenticated locally.

   • Download the Upsun CLI
   • Download the Platform.sh CLI
   • Download the WebPaaS CLI

4. Create an organization: Before you can create your first project, you must configure an organization.  Organizations are mandatory to manage projects, billing, and more.

   upsun organization:create

   or

   platform organization:create

5. Create a new project: Run one of the following commands with the region parameter set to FR-3, the OVH region hosted in Graveline like your previous Web PaaS project:

   upsun project:create --region=fr-3.platform.sh

   or

   platform project:create --region=fr-3.platform.sh

   Then answer the questions: choose the right organization, set a name to your project, and set the name of your production environment.

   The project creation process will return you two important pieces of information:

   • Project ID named $PROJECT_ID in the next steps
   • Git URL named $GIT_URL in the next steps

   Please, save them both, they will be required in the following steps.

6. Invite collaborators: Invite your collaborators to the project by running the user:add command, and answering the interactive questions.

   upsun user:add

   or

   platform user:add

Migrate code

Once your project has been set up, it’s time to move your application code and (if relevant) source code integrations to the new destination.

1. (Option 1) Configure source integration: If you use a source integration with GitHub, GitLab, or Bitbucket for your Web PaaS project, you’ll need to add the same integration to your new project. If you don’t use source integration, you can pass this step, and go directly to the next step.

   upsun integration:add

   or

   platform integration:add

   Run the command and answer the questions. Once the integration has been configured, your environments should now be visible on either Upsun or Platform.sh. The initial activities may fail since the configuration needs to be updated, but that will be updated in the next steps.

2. (Option 2) Clone project locally from OVH Web PaaS: Now that your new project is ready, we can start the code migration. For that, we must have your Web PaaS project cloned locally.

   Run the get command with the Web PaaS CLI:

   webpass get $YOUR_WEBPAAS_PROJECT_ID

   If you don’t know your Web PaaS project ID, it’s displayed on your project Console at https://eu.console.webpaas.ovhcloud.com/.

   Connect the local repository to the new project you created ($PROJECT_ID):

   upsun project:set-remote $PROJECT_ID

   or

   platform project:set-remote $PROJECT_ID

   Then push your code:

   git push platform $OLD_PRODUCTION_BRANCH:$NEW_PRODUCTION_BRANCH
   # or
   git push upsun $OLD_PRODUCTION_BRANCH:$NEW_PRODUCTION_BRANCH

   Where:

   • $OLD_PRODUCTION_BRANCH is the branch name of your production environment on Web PaaS, usually Master or Main, 
   • $NEW_PRODUCTION_BRANCH is the branch name of your production environment on your new project as defined during creation.

   Once the code is pushed, it triggers a build, and your app will be deployed on your new project. 

3. Update configuration files:

   If you’re migrating to Platform.sh, you can skip this step, as your configuration is already compatible. Continue below if you are migrating to Upsun.

   Create a new branch to update your configuration.

   git checkout -b upsunfiy

   Compared to Platform.sh where there are three configuration files (routes, application, services), on Upsun everything is regrouped in a single config.yaml file. To ease the migration our team has developed a conversion tool that you can download from GitHub.

   Copy the binary convsun on your local machine from the Releases page linked above, then run:

   convsun --src $WEBPAAS_PROJECTPATH

   Where $WEBPAAS_PROJECTPATH is the local path to your Web PaaS project. The converter will add a new file to the .upsun folder containing the new configuration. Add this new folder to your project Git repository and commit the change:

   git add .upsun/config.yaml
   git commit -m "Add Upsun configuration"
   upsun push

   If you are using a source integration, you will need to review these changes deployed as expected on a pull request. Through that integration, you may also need to activate (upsun environment:activate pr-XX) the environment manually to review. If you are not using a source integration, you may likewise need to activate the environment manually (upsun environment:activate).

   When you are satisfied that the project appears to have deployed as expected, merge it either from your Git hosting service or directly in the Web Console.

Recreate variables

Let’s now focus on the variables. There are two types of variables: at the project level and the environment level. You can list all the existing variables with the following command:

webpaas variable:list

You’ll need to recreate all these existing variables with the same attributes. To do so, run the following command for each of them:

upsun variable:create

or

platform variable:create

Migrate data

With code and variables migrated, next is the data within our services and writable mounts.

1. Migrate databases:

   To sync the database, the easiest way is to chain two CLI commands. Get into your Web PaaS project folder and run the following command:

   webpaas db:dump -o -e $OLD_PRODUCTION_BRANCH | upsun sql -p $PROJECT_ID -e $NEW_PRODUCTION_BRANCH

   or

   webpaas db:dump -o -e $OLD_PRODUCTION_BRANCH | platform sql -p $PROJECT_ID -e $NEW_PRODUCTION_BRANCH

2. Recreate mounts:

   Get into your Web PaaS project folder and run the following command to list all the existing mount points:

   webpaas mounts

   For each of the mount point, run the following command to download the remote content to your local machine:

   webpaas mount:download -m $MOUNT_PATH --target=$LOCAL_MOUNT_FOLDER

   Then one of the following to upload them to the new project:

   upsun mount:upload -p $PROJECT_ID --source=$LOCAL_MOUNT_FOLDER --mount=$MOUNT_PATH

   or

   platform mount:upload -p $PROJECT_ID --source=$LOCAL_MOUNT_FOLDER --mount=$MOUNT_PATH

Configure integrations

You may have configured other integrations on your Web PaaS project like:

• health.email
• webhook
• script
• health.slack
• …

You can use the following command to list all the existing integrations:

webpaas integrations

You can configure them in your new project:

upsun integration:add

or

platform integration:add

Going live

In these final steps, you will update the domain configuration of the new project to complete the migration.

1. Verify project running as expected: Give the project a thorough look. Following the steps below will complete the migration, so be sure your project is functioning as expected at this point.

2. Redeem your voucher: Log into your account on the management console. Then:

   • Select the organization where you have created your new project,
   • Expand the menu in the top-left corner and click Billing,
   • Select the Vouchers tab, and then select Redeem Voucher,
   • Enter the voucher code you have received already for the migration. 

3. Upgrade to production resources: Once your voucher has been saved, you can configure your project for production.

   • Case 1: Upsun: Upsun does not have the concept of “plan” as there is on Platform.sh. Your project was initialized with some default set of resources (disk, CPU, RAM), and does not require changes to these setting in order to add a domain and go live. However, those default resources will likely not match what you have on Web PaaS, so they will need updating to keep everything working properly.

     Review the currently allocated resources:

     upsun resources:get -p $PROJECT_ID

     Then adjust those resources interactively if necessary:

     upsun resources:set -p $PROJECT_ID

   • Case 2: Platform.sh: At creation, your project was set on a Development plan, but that must be upgraded to a production plan. Navigate to your project, click the three dots menu in the upper right hand corner and select Edit plan. From there, choose the appropriate plan and associated resources and save your choice.

4. Configure your domains: First, list all the existing domains of your Web PaaS project:

   webpaas domain:list

   With this list in hand, follow the instructions below to set up your production domain on the project:

   • Upsun: set up a custom domain
   • Platform.sh: set up a custom domain

5. Reset your DNS TTL: Once the TTL has expired, the web traffic should be directed to your new project. Ensure that there is no longer any traffic on your Web PaaS project by checking the logs:

   webpaas logs access

   If everything is fine, then adjust the TTL of your DNS entries to their previous value.