Converting from Upsun Fixed (formerly Platform.sh)

There are two ways to change the configuration files of your Upsun Fixed (formerly Platform.sh) projects to make them Upsun compatible.

Convert projects with the CLI
Convert projects manually

Before you begin

You need:

An Upsun Fixed (formerly Platform.sh) application that works and is ready to be built
The Upsun CLI installed locally

Convert with the CLI

To assist with converting applications from Upsun Fixed to Upsun, the Upsun converting tool is available as part of the Upsun CLI. This feature automates the conversion of Upsun Fixed config files into a format required by Upsun, significantly reducing manual effort.

Key functions

The converting tool performs the following transformations:

Generation of Upsun config.yaml

Creates a new config.yaml file - the primary configuration file for Upsun projects.
Extracts relevant information from .platform.app.yaml, services.yaml, applications.yaml, and routes.yaml.

Refactoring of obsolete or incompatible fields

Removes resource-related fields that are not applicable in Upsun. This includes:

Disk values
Size settings (e.g., S, M, L)
Legacy resources blocks
Any deprecated or unsupported container options in the source configuration

Mount and storage adjustments

Converts mounts of type local into Upsun’s storage format to support horizontal scaling and infrastructure consistency.
Ensures that volumes and file persistence are aligned with how Upsun manages data across containers.

Reorganization of custom service configuration

Moves custom configuration for services such as Solr into the .upsun/ directory, which is used to hold project-specific overrides and custom assets.

Support for cron jobs

Identifies cron jobs defined in Upsun Fixed and provides guidance on how to replicate similar functionality in Upsun.
Flags any cron schedules requiring special support and prepares the config.yaml accordingly.

Example usage

upsun convert

You will be prompted to enter the path to the Upsun Fixed project you would like to convert.

The conversion then takes place within the Upsun CLI and outputs the updated config.yaml file to the specified destination directory.

Convert manually

The CLI tool described above allows you to easily convert projects from Upsun Fixed to Upsun, however, if your project has custom requirements that require a more hands-on approach, you can manually update your Upsun Fixed configuration to be compatible with Upsun.

Manual conversion gives you full control over the transition process and can be useful for projects with non-standard setups or advanced customizations.

Follow the steps below to begin a manual migration.

1. Export your source Upsun Fixed project

Start by exporting everything you might need from your current app. This includes data in databases, files on a file system, and for some apps, such as Drupal, configuration that you need to export from the system into files.

If you do not already have an organization created on Upsun, create one:

upsun org:create

Then run the following command to create a project:

upsun project:create

When prompted, fill in details like the project name, region, and the name of your organization.

Create a new project from scratch.

If you do not already have an organization created to put the project, you’ll first be instructed to create one.

Once you have done so, select that organization from the dropdown, and select Create from scratch.

In the form, fill in details like the project name and region. You’ll be able to define resources for the project after your first push.

3. Convert your configuration files

The exact configuration you want depends on your app. You likely want to configure three areas:

The app itself – this is the only required configuration
Services
Routes

Note

If you’d rather not do this manually, you can use the converting tool via the Upsun CLI to make all the necessary changes to your configuration files.

When you’ve added your configuration, make sure to commit it to Git.

4. Optional: Define a resource initialization strategy

By default, when you first deploy your project, Upsun allocates default resources to each of your containers. If you don’t want to use those default resources, define your own resource initialization strategy before pushing your code.

Alternatively, you can amend those default container resources after your project is deployed.

5. Push your changes

The way to push your code to Upsun depends on whether you’re hosting your code with a third-party service using a source integration. If you aren’t, your repository is hosted in Upsun and you can use the CLI or just Git itself.

Get your project ID by running the following command:

upsun projects

Add Upsun as a remote repository by running the following command:

upsun project:set-remote PROJECT_ID

Push to the Upsun repository by running the following command:

upsun push

When you try to push, any detected errors in your configuration are reported and block the push. After any errors are fixed, a push creates a new environment.

Set up the integration for your selected service:

Then push code to that service as you do normally. Pushing to a branch creates an environment from that branch.

Note that the source integration doesn’t report any errors in configuration directly. You have to monitor those in your project activities.

Add an SSH key.
In the Console, open your project and click Code .
Click Git.
From the displayed command, copy the location of your repository. It should have a format similar to the following:

abcdefgh1234567@git.eu.upsun.com:abcdefgh1234567.git

Add Upsun as a remote repository by running the following command:

git remote add upsun REPOSITORY_LOCATION

Push to the Upsun repository by running the following command:

git push -u upsun DEFAULT_BRANCH_NAME

When you try to push, any detected errors in your configuration are reported and block the push. After any errors are fixed, a push creates a new environment.

6. Import data

Once you have an environment, you can import the data you backed up at step 1. The exact process may depend on the service you use.

For SQL databases, for example, you can use a version of this command:

upsun sql < BACKUP_FILE_NAME

For any potential more details, see the specific service.

7. Import files

Your app may include content files, meaning files that aren’t intended to be part of your codebase so aren’t in Git. You can upload such files to mounts you created. Upload to each mount separately.

Suppose you have the following mounts defined:

.upsun/config.yaml

applications:
 myapp:
   mounts:
     'web/uploads':
       source: local
       source_path: uploads
     'private':
       source: local
       source_path: private

instance mounts on Upsun are the equivalent of local mounts on Upsun Fixed. To ensure continuity when converting from Upsun Fixed to Upsun, the local mount type works as an alias for the instance mount type.

However, it is recommended to change the type of your local mounts to instance or another supported mount type.

For example:

.upsun/config.yaml

applications:
 myapp:
   mounts:
     'web/uploads':
       source: instance
       source_path: uploads
     'private':
       source: instance
       source_path: private

Then, to upload your files, run a command similar to the following:

upsun mount:upload --mount web/uploads --source ./uploads
upsun mount:upload --mount private --source ./private

Alternatively, you can upload to your mounts using a different SSH method.

Optional: Add variables

If your app requires environment variables to build properly, add them to your environment.

What’s next

Now that your app is ready to be deployed, you can do more:

Add a domain.
Set up for local development.
Configure health notifications.
For monitoring and profiling, integrate Blackfire.

Integrated environments

Supported environments