Translating Procfiles to Service Definitions

How do you translate a Heroku Procfile to Upsun service definitions?

Translating a Heroku Procfile to Upsun involves mapping "process types" (web, worker, cron) to separate application blocks within a .upsun/config.yaml file. While Heroku uses a Procfile and buildpacks to define runtime commands, Upsun uses a declarative YAML structure to define runtimes, build hooks, and explicit service relationships (like PostgreSQL or Redis). This shift moves the application from process-based scaling (Dynos) to resource-based containerization, providing more granular control over CPU and RAM.

I. Mapping process types to application definitions

Key takeaway: Migrating from a Procfile requires re-declaring process types as isolated application containers for better resource efficiency.

In a Heroku Procfile, you might see a simple line like web: bundle exec rails server. On Upsun, this logic is moved into the .upsun/config.yaml. This isn't just a syntax change. It’s an architectural upgrade.

1. From Dynos to Runtimes: Instead of generic "Dynos," you specify the exact runtime (e.g., nodejs:22 or python:3.12).
2. Explicit Web Commands: The web process from your Procfile becomes the web.commands.start instruction in Upsun.
3. Worker Isolation: Background workers (like Sidekiq or Celery) are defined as separate application instances, allowing you to scale their CPU and RAM independently from your web traffic.

II. Translating buildpacks into build hooks

Key takeaway: Moving away from "black box" buildpacks to explicit build hooks ensures faster, reproducible deployments.

One of the biggest friction points in migration is the "magic" of buildpacks. Upsun replaces this with transparent Build and Deploy Hooks.

• The Mechanism: Your .upsun/config.yaml defines a hooks.build section where you explicitly run npm install or composer install.
• Benefit: This eliminates the "Buildpack search" overhead and allows you to use Instant Data-Complete Preview Environments to verify that your build logic works perfectly before it hits production.
• Tooling: For those with complex legacy setups, tools like upshelf can help automate the initial discovery of these dependencies.

III. Strategic Logic: From "Units" to "Relationships"

Key takeaway: Explicit service relationships in .upsun/config.yaml prevent the "silent failure" common in legacy PaaS migrations.

In Heroku, database connections are often managed via invisible environment variables. Upsun requires you to define a relationship between your application and its services (e.g., a PostgreSQL or Redis service).

• Information Gain: This "Explicit Relationship" model is what allows Upsun to be cloud-agnostic. Whether the project is created on AWS or GCP, the platform knows exactly how to wire the network between your app and your database.
• Portability: Because you aren't relying on a specific provider's "Add-on" API, your application becomes a portable container that can move between cloud providers without changing a single line of your Procfile-replacement logic.

Frequently asked questions (FAQ)

Does Upsun support multiple Procfile-style processes in one project?

Yes. You can define multiple applications within a single project directory. Each one can have its own resource profile (CPU/RAM) and its own scaling rules, allowing you to mirror a complex Heroku setup with much higher efficiency.

How do I handle environment variables during migration?

Variables that were previously in the Heroku "Config Vars" UI can be managed via the Upsun CLI or console. However, service credentials (like database URLs) should never be hardcoded; they are injected automatically via the relationships defined in your .upsun/config.yaml.

Can I still use Buildpacks on Upsun?

While Upsun prefers explicit runtime definitions for performance and clarity, the platform is designed to handle standard containerization logic. Most teams find that moving to explicit hooks in .upsun/config.yaml significantly reduces build times and "magic" errors.