Transforming Symfony monolith to multi-apps: a step-by-step guide

This blog post is based on Florent Huck, Developer Advocate at Upsun, at SymfonyCon 2023. We utilized AI tools for transcription and to enhance the structure and clarity of the content.

The journey from a single monolithic application to a multi-application architecture doesn't have to be daunting. At a recent developer conference, Florent from Upsun's Developer Relations team shared a practical step-by-step guide on how to refactor a monolith into multiple applications using Upsun.

Why move from one app to many

According to Upsun’s data, an overwhelming 90% of Symfony applications hosted on their platform are monoliths, with only 10% using two or more applications. This statistic reveals a significant opportunity for developers to modernize their architecture and decouple their applications for better scalability and maintainability.

The example project is the “Bigfoot” workshop site. It started as a Symfony 6.2 application on PHP 8.3 with PostgreSQL 15 and no admin interface. For the workshop, the team needed the same site in other languages and a simple way to manage content. That pushed the move from one app to a multi-app setup:

• Keep Symfony as the core app and add API Platform to expose data.
• Add an admin using the API Platform Admin components.
• Add a Gatsby “white label” front end that reads from the API.
• Add a Mercure server for real-time updates.

What Upsun handles for you

Upsun sits between your code and a major cloud provider you choose. You do not manage servers. You push your code, set a simple YAML config, and Upsun handles hosting.  A new project gets the default architecture out of the box: CDN, automatic backups, caches, search, and a database. Even the demo app includes PostgreSQL without requiring any additional steps. Certificates are managed for you with automatic renewals, so you don't have to worry about TLS certificate management.

If you want a quick look at how Upsun works, start here on the Upsun website.

Four commands to live

The deployment process is straightforward. With just four commands using the Symfony CLI, you can have your application up and running:

1. Create a demo project with the Upsun option
2. Initialize an existing Symfony project (which auto-generates the necessary config files)
3. Follow the standard Git workflow (add, commit)
4. Create and push your project

From there, every Git branch gets its own live environment with a stable URL and a valid certificate. You test in an environment that behaves like a production environment. Thanks to Fabien Potencier's work integrating Upsun CLI tools into the Symfony CLI, everything can be managed through a single interface.

Case study: The Bigfoot website

To demonstrate the refactoring process, Florent used a real example: the Bigfoot website, originally created for Blackfire workshops. This blog-like site about Bigfoot sightings was built as a monolith using:

• Symfony 6.2 (updated to work with PHP 8.3)
• PostgreSQL 15
• Extensive fixtures
• No administration interface

The goal was to transform this single application into multiple interconnected applications:

• A Symfony application serving the main Bigfoot site
• An API Platform admin component for content administration
• A Gatsby frontend as a white-label solution
• A Mercure server for real-time communication

Step-by-step refactoring process

1. Create a new environment

Never push directly to production. Start by creating a new branch using the Symfony CLI, which automatically creates both a local Git branch and a corresponding environment with the same data as your previous branch.

Upsun automatically generates SSL certificates and manages their renewal, eliminating the pain point that many developers face when managing certificates manually.

2. Adapt folder structure

The transformation requires reorganizing your folder structure. Instead of having a single application with a .upsun configuration folder, you create:

• A root .upsun folder containing the main configuration
• Separate folders for each application containing their respective source code
• Each application gets its own customized configuration

3. Add API Platform to Symfony

Install the API Platform core bundle in the Symfony app. It exposes a REST API from your Doctrine entities. When an entity changes, the REST endpoints reflect that change. That is how the Gatsby front end and the admin will read and write content.

4. Manage configuration 

Upsun uses a single YAML configuration file. This file contains three main sections:

Routes configuration: Each application gets its own routing block. You define URL patterns, such as using the default domain for the main app, /admin for the administration interface, /site for the Gatsby frontend, and subdomains for services like Mercure.

Services configuration: Adding services is straightforward. Under services, define the data stores each app needs:

• type: postgresql with version: 15 for the database.

 For example, to add Redis, you simply specify:

redis:

  type: redis

  version: 7

You can add small config flags here (such as max memory policy). Upsun transforms this simple block into the right managed service on the cloud you've chosen. You do not write provider-specific setup scripts.

Application configuration: For each application, you define:

• Runtime: Specify major and minor versions (for example, PHP 8.3). Each deploy uses the latest maintenance release for that line.
• Source root: The folder where that app’s code lives.
• Relationships: Link the app to services (for example, the Symfony app to PostgreSQL).
• Mounts: Writable paths such as var/ for cache and logs.
• Web: Where the web root and front controller live (for example, public/index.php).
• Build and deploy steps: Use Symfony Configurator’s symfony build and symfony deploy to clear cache, run migrations, and run any custom commands you need. Add cron jobs and workers if needed.

Push, test, and promote

When your config and code changes are ready:

• Push your branch: symfony push deploys your branch environment.
• Upsun prints a small graph of apps and services, allowing you to confirm the relationships.
• Routes are generated from your routing rules, such as:
  • Default site at the root.
  • Admin at /admin.
  • Gatsby site at a path like /site.
  • Mercure on a subdomain.

Test each route. When you are satisfied, run symfony merge. Upsun promotes the build-to-production.

Resource allocation: what changes with Upsun

Upsun introduces a resource:set CLI command that allows per-container resource allocation. You can specify exactly how much CPU and RAM each container receives, making the platform more flexible and cost-effective.

This granular control means you can:

• Downsize resources for development environments
• Test different resource configurations on dedicated environments
• Pay only for what you provision across all environments

Continuous integration

Upsun supports integration with GitHub, GitLab, and Bitbucket. When you create a new branch and push it to your repository, Upsun automatically deploys your source code to a dedicated environment, enabling proper continuous integration.

However, developers must be mindful of resource usage since each environment contributes to the monthly bill. Unlike fixed-size preview environments, Upsun's flexible model means your feature branches can impact costs if not adequately managed.

Best practices

Deploy often, deploy confidently

Upsun's motto is "Deploy Friday" (and even "Deploy on Black Friday"). The philosophy is simple: if you can test your features in a production-like environment, you can confidently push all necessary source code to your Git branch.

This approach eliminates the common developer nightmare: "I don't understand why staging crashed; it works locally." With proper environment parity, missing files will cause failures in your development environment before reaching production.

Git workflow adaptation

The multi-application architecture requires slight modifications to your Git workflow, but the core process remains familiar. The key is to deploy frequently and test thoroughly in environment branches before merging to production.

Common pitfalls and solutions

During the development of the multi-application Bigfoot site, several challenges emerged:

1. Routing Issues: When using URI elements to recognize applications, you must report the first URI element in both the route name and path configuration.
2. Environment Variables: Local development typically uses localhost:8000, but production uses dynamic URLs. The .environment file solution offers the flexibility required for various deployment scenarios.
3. Resource Management: Without careful planning, development environments can consume as many resources as production, significantly impacting costs.

The future of multi-application architecture

This approach to refactoring opens up numerous possibilities for modern web development. By decoupling your monolith into specialized applications, you gain:

• Better separation of concerns
• Improved scalability options
• Technology diversity (mixing Symfony, Gatsby, and other frameworks)
• Enhanced development team workflow

The Bigfoot project successfully demonstrated how a traditional Symfony monolith can evolve into a modern, multi-application architecture while maintaining all functionality and adding new capabilities, such as real-time communication and advanced administration interfaces.

Where this leaves you

You do not have to jump into a microservices maze. You can split a monolith into several apps where it makes sense, such as API, admin, frontend, and real-time. Upsun’s single YAML, managed services, auto HTTPS, and branch environments make that move safe and repeatable. When you are ready, merge and go live.