Published on
Is it worth migrating from Heroku to a cloud in Brazil? Step by step
Migrating from Heroku to Zenifra pays off when your users are in Brazil and you want to pay in Brazilian reais, with PIX, boleto, or card and without IOF: a Basic app with Heroku Postgres Essential-0 costs US$12, which becomes R$67.84 on a card at the November 5, 2026 PTAX rate plus 3.5% IOF, versus R$42.00 for an equivalent setup on Zenifra. It does not pay off if you depend on Heroku marketplace add-ons with no equivalent, on Private Spaces, or on users concentrated in the United States and Europe; this guide shows the math for three sizes and the step-by-step process from the Zenifra docs, from inventory to rollback.
When migrating from Heroku pays off, and when it does not
Heroku is a mature PaaS, with more than a decade of production apps and a large add-on marketplace. For teams serving users in Brazil, though, three points weigh on every invoice. The first is location: the heroku regions command lists the Common Runtime only in the United States and Europe, and Private Spaces in Dublin, Frankfurt, London, Montreal, Mumbai, Oregon, Singapore, Sydney, Tokyo, and Virginia, none in South America. The second is billing: according to the Heroku help center, invoices are charged automatically to a credit card every month, in US dollars, with no PayPal, ACH, or wire transfer. The third is the entry price: there is no free plan, and the US$5 Eco dyno is for personal accounts only and sleeps after 30 minutes of inactivity.
Moving to Zenifra makes sense when the app already follows the classic Heroku design: a web process, maybe a worker, Heroku Postgres, a Key-Value Store (formerly Heroku Redis), and a few Heroku Scheduler tasks. Each of these pieces has a direct equivalent on Zenifra, and the code usually moves unchanged, because deployment comes from the same GitHub repository. The application runs on infrastructure in Brazil, and billing is in Brazilian reais, by PIX, boleto, or card, with no currency exchange and no IOF.
It does not make sense in a few cases, and it is better to know before you start. If your product depends on Heroku marketplace add-ons with no equivalent, you will need to keep your accounts with those providers or switch tools. If your company requires Private Spaces, network isolation, and regions in several countries for compliance, Heroku delivers that and Zenifra has no equivalent offering. If most of your users are in the United States or Europe, a region close to them is worth more than the exchange-rate savings. And if your revenue is in US dollars, currency swings stop being a risk, because revenue and cost move together.
There is also an operational point: the Zenifra docs copy the database with pg_dump and pg_restore, which requires freezing writes on Heroku during the final copy. For most applications that means a few minutes in maintenance mode, measured in a rehearsal. If your business cannot accept any frozen-write window, talk to support before setting a date.
- Worth migrating: users in Brazil, an app in Node.js, Python, Bun, Go, Java, or PHP (or a Docker image), PostgreSQL and Redis as databases, and a preference for paying in reais with PIX or boleto.
- Think twice: heavy reliance on add-ons with no equivalent, a Private Spaces requirement, users outside Brazil, or revenue in US dollars.
What it costs before and after, in three application sizes
To compare, we built three typical Heroku setups and picked the closest Zenifra plan by memory. Heroku prices were read on the official page on November 6, 2026. The conversion uses the November 5, 2026 selling PTAX rate published by the Central Bank of Brazil, R$5.4621 per US dollar, and the converted amount gets the 3.5% IOF tax that applies to international card purchases (Decree 6,306/2007, art. 15-B, item VII, as worded by Decree 12,499/2025). Zenifra prices come from the public plan catalog, the same one behind the site calculator, on the same day.
To keep the comparison fair, the Zenifra column already includes PostgreSQL disk at the same size as the Heroku plan. On Zenifra, PostgreSQL disk is billed separately at R$0.20 per GB per month, while Heroku Postgres plans include disk: 1 GB on Essential-0, 10 GB on Essential-1, and 64 GB on Standard-0.
| Scenario | On Heroku | US dollar price | At the Nov 5, 2026 PTAX | With 3.5% IOF | On Zenifra, in reais |
|---|---|---|---|---|---|
| Small app | Basic (0.5 GB) + Postgres Essential-0 (1 GB disk) | US$12.00 | R$65.55 | R$67.84 | Basic (0.5 vCPU, 512 MB) R$29.90 + DB-Starter R$11.90 + 1 GB disk R$0.20 = R$42.00 |
| App with a worker and Redis | 2 × Basic (web and worker) + Postgres Essential-1 (10 GB) + Key-Value Mini (25 MB) | US$26.00 | R$142.01 | R$146.99 | 2 × Basic R$59.80 + DB-Starter R$11.90 + 10 GB disk R$2.00 + Valkey Key-Value DB-Starter R$11.90 + 1 GB disk R$0.20 = R$85.80 |
| SaaS with two instances | 2 × Standard-2X (1 GB) + Postgres Standard-0 (4 GB RAM, 64 GB disk) | US$150.00 | R$819.32 | R$847.99 | 2 × Premium (1 vCPU, 1 GB) R$125.80 + DB-Premium (2 GB) R$129.90 + 64 GB disk R$12.80 = R$268.50 |
In the second scenario, a Valkey Key-Value database on DB-Starter (0.3 vCPU, 256 MB, with AOF) replaces Key-Value Mini and works both for cache and sessions and for Sidekiq or Celery queues, with persistence. If Redis only holds cache and you prefer a memory-only profile, cache-starter costs R$34.90 and brings the total to R$108.60, still below Heroku’s R$146.99 with IOF.
The third scenario needs a caveat: Zenifra has no PostgreSQL plan with 4 GB of memory. DB-Premium has 2 GB, and the next one, DB-Enterprise, has 8 GB for R$489.00. If your database needs more than 2 GB of memory, the total with DB-Enterprise and 64 GB of disk is R$627.60, still below Heroku’s R$847.99 with IOF. The connection limit also changes: Standard-0 accepts 120 connections, DB-Premium 147, and DB-Enterprise 598.
Two honesty notes. Your card issuer applies its own spread on top of the exchange rate, so the real US dollar invoice tends to land above what the table shows. And to rehearse the migration, hourly billing charges only for the hours the projects are running.
How Heroku concepts map to Zenifra concepts
Most of the migration work is vocabulary translation. A Heroku app becomes an HTTP project on Zenifra, and each Procfile line becomes a project field or a separate project. The table below reproduces the mapping from the official Heroku migration guide in the Zenifra docs, with two additions the same guide explains in its text: other add-ons and files written to the dyno disk.
Two points deserve attention right away. Zenifra has no step equivalent to the release phase, so the release: line in the Procfile becomes the beginning of the Start Command or a manual step, which changes how you run migrations. And each process other than web, such as worker or clock, becomes another project from the same repository, with Private Exposure, because a Zenifra project runs one start command at a time.
| On Heroku | On Zenifra |
|---|---|
| App | HTTP project |
web process in the Procfile | The project’s Start Command |
worker process (or any other name) | Another project with the same repository, Private Exposure, and the worker command |
Release phase (release:) | Beginning of the Start Command or a manual step |
| Buildpack | Runtime and Version (Node.js, Python, Bun, Go, or Java) or OCI image |
| Config Vars | Environment Variables |
Number of web dynos | Desired Instances or auto-scaling |
| Heroku Scheduler | Scheduled jobs |
| Heroku Postgres | Managed PostgreSQL |
| Heroku Key-Value Store (Heroku Redis) | Managed cache or Key-Value |
| Review Apps | Preview Environments |
heroku maintenance:on | Use it on Heroku during the final data copy |
| Other add-ons (email, monitoring) | Keep working if you keep your account with the add-on provider |
| Files written to the dyno disk | Persistent storage or Storage (Armazém), S3-compatible |
PHP also runs as a runtime on Zenifra: the guide lists frankenphp php-server --listen :$PORT --root public/ for it. Ruby, .NET, and other languages outside the runtimes are deployed as a Docker Image, built from a Dockerfile and pushed to a registry, and the Zenifra GitHub Action automates the build and deploy on every push.
Step 1: take inventory of the Heroku app
Before creating anything on Zenifra, list everything the app uses: processes, databases, cache, variables, domains, scheduled tasks, and external integrations. The general plan in the docs starts here because each item becomes a decision: a process becomes a project, a scheduled task becomes a Job, and a variable pointing to an add-on needs a new value. The commands below use the Heroku CLI; replace my-app with your app name.
Config Vars come out all at once with heroku config --shell. The generated file contains secrets: do not commit it, and delete it after the migration. When reviewing it, split it into three groups. DATABASE_URL and REDIS_URL were created by add-ons and point to Heroku databases, so they will get new values. Variables prefixed with HEROKU_ belong to the platform and should only be copied if your code uses one of them, with an equivalent value. Variables from other add-ons, such as email or monitoring, keep working if you keep your account with the add-on provider.
From the Procfile, write down the command for each process type (release, web, worker, and others). Without a Procfile, Heroku uses the buildpack default, such as the start script in package.json for Node.js. Also note how many dynos of each type are running, the buildpacks, the domains and the DNS target of each, whether the Deploy tab has Automatic deploys on and which branch it publishes, and the Scheduler task list with each command and frequency. If the repository has an app.json, it lists the variables, add-ons, and scripts used by Review Apps.
The language version comes from the repository itself, and you will need it to choose the same major Version in the Console: engines.node in package.json (Node.js), .python-version or runtime.txt (Python), the go line in go.mod (Go), java.runtime.version in system.properties (Java), require.php in composer.json (PHP), and the ruby entry in the Gemfile (Ruby).
# Export the Config Vars (use --json if you prefer JSON)
heroku config --shell -a my-app > heroku.env
# How many dynos of each type are running
heroku ps -a my-app
# Buildpacks, which point to the Runtime on Zenifra
heroku buildpacks -a my-app
# Domains and the DNS target of each
heroku domains -a my-app
# List of scheduled tasks
heroku addons:open scheduler -a my-appStep 2: create the databases and the project from GitHub
Create the managed PostgreSQL first and, if the app uses Redis, the cache or Key-Value database. That way the connection URLs already exist when you add the project variables. Pick the same PostgreSQL major version as Heroku or a newer one: Zenifra offers versions 15, 16, 17, and 18, with 18 as the default. The full database password only appears at creation or after a rotation, so save the connection URI at that moment.
Then, in the Console, click + Create project, choose HTTP Application and the plan. Under Advanced Settings, choose Git repository as the Project Source, GitHub (or Forgejo) as the Git provider, the same repository, and the branch Heroku publishes. The language buildpack becomes the Runtime field, the repository version becomes Version, the app folder becomes Root directory (use . for the root), the web: line becomes the Start Command, and Automatic deploys on becomes the Automatic by branch deployment mode. With it off, use Manual mode.
Heroku runs some build steps on its own; on Zenifra each step is explicit in the Build Command. The table below is the one from the official guide. In Node.js, the heroku-prebuild, heroku-build, and heroku-postbuild scripts do not run: move what they did into the Pre-build Command or the Build Command. Installation uses npm ci and requires a committed package-lock.json, so apps using Yarn or pnpm need to generate and commit that file first. NPM_CONFIG_PRODUCTION is not needed, because devDependencies are available during the build.
In Python, Zenifra installs dependencies from requirements.txt. If Heroku used poetry.lock, uv.lock, or Pipfile.lock, export a requirements.txt with poetry export -f requirements.txt --output requirements.txt or uv export --format requirements-txt > requirements.txt and commit the result.
| Language | Build Command | Start Command |
|---|---|---|
| Node.js | npm run build if package.json has a build script; empty otherwise | web: line in the Procfile or npm start |
| Python (Django) | python manage.py collectstatic --noinput | gunicorn project.wsgi --bind 0.0.0.0:8000 |
| Python (Flask, FastAPI) | empty | web: line with --bind 0.0.0.0:8000 or --host 0.0.0.0 --port 8000 |
| Go | go build -o app ./cmd/server (folder of the main package) | ./app |
| Java (Maven) | ./mvnw -B -DskipTests package or mvn -B -DskipTests package | java -jar target/*.jar |
| PHP | empty | frankenphp php-server --listen :$PORT --root public/ |
Step 3: variables, port, release phase, workers, and Scheduler
Add the Config Vars under Environment Variables, replacing DATABASE_URL and REDIS_URL with the URIs of the new databases. Zenifra does not inject DATABASE_URL automatically: copy the database URI in the Console and create the variable in the project. Each project accepts up to 50 variables, with values up to 32,760 characters, and saving a change restarts the instances. Variables used at build time, such as NEXT_PUBLIC_* or VITE_*, are baked into the build output: to apply a new value, choose New build in Build logs or push a new commit.
The port is the most common difference between the platforms. On Heroku, the web process listens on the port in the PORT variable, chosen by the platform. On Zenifra, the port is the project’s Port field. Since your code already reads PORT, set both to the same value, for example Port 3000 and the variable PORT=3000, and make sure the app listens on 0.0.0.0, not localhost. As on Heroku, Zenifra terminates HTTPS before forwarding the request, so keep your framework’s trusted-proxy settings, such as trust proxy in Express, config.force_ssl in Rails, or --proxy-headers in uvicorn.
The release phase has no equivalent step, and the docs give two options. The first is to run the migration together with the start, such as npx prisma migrate deploy && npm start or python manage.py migrate && gunicorn .... The command runs every time an instance starts, so it must be idempotent, and with several instances all of them run it, so prefer tools that lock the database during the migration. The second is manual: run the migration from your machine, pointing at the Zenifra database, before deploying the version that depends on it, which is the safest choice for long migrations.
Each process other than web becomes a project: create another HTTP project with the same repository and branch, choose Private - no public route under Exposure, use the worker command as the Start Command (for example bundle exec sidekiq or celery -A app worker), and add the same variables as the web project. The clock process can become a private project the same way or be replaced by Scheduled jobs. Each Heroku Scheduler task becomes a Scheduled job with GitHub Repository as the Task source, the same Runtime, the command in Task command, and the variables it needs.
| Frequency in Heroku Scheduler | Cron expression on Zenifra |
|---|---|
| Every 10 minutes | */10 * * * * |
| Every hour, at minute 30 | 30 * * * * |
| Every day at 06:00 UTC | 0 6 * * * |
| Weekdays at 09:00 UTC (no Scheduler equivalent) | 0 9 * * 1-5 |
Both platforms use UTC. Zenifra Jobs are billed per minute of execution, in reais (the job-starter plan costs R$0.0001666666 per minute), run at most one execution at a time, stop an execution that exceeds 60 minutes, and do not retry when they fail. On Heroku, Scheduler is a free add-on, but it runs tasks on one-off dynos that count toward your monthly usage, and Heroku’s own documentation says execution is expected but not guaranteed.
Files uploaded by users deserve a line in the inventory: on Heroku, whatever is written to the dyno disk disappears when it restarts. On Zenifra, store files in persistent storage or in Storage (Armazém), which is S3-compatible and available to every organization in the Console. If the app already uses an S3 bucket, it keeps working with the same variables.
Step 4: copy Heroku Postgres and the Key-Value Store
The simplest path for small databases is Heroku’s own backup. heroku pg:backups:capture creates the backup, heroku pg:backups:download downloads the latest.dump file, and pg_restore --list confirms the file is intact before you restore it. Heroku’s documentation recommends PGBackups for moderately loaded databases up to 20 GB; above that, or with many schemas and large objects, the backup can time out.
For larger databases, or to copy directly, get the Heroku database URL with heroku pg:credentials:url DATABASE -a my-app and use pg_dump in custom format. Use a pg_dump of the same major version as the database or newer. The restore on Zenifra uses the URI from the Console, which already turns TLS on with sslmode=require, and the --no-owner --no-acl options avoid permission errors with users that do not exist in the new database. --jobs=4 restores in parallel and shortens the cutover window.
After restoring, validate. Compare row counts of the main tables in both databases with SELECT count(*) and run the application’s smoke tests against the new database. Do a full rehearsal before cutover day, timing the capture, download, and restore: that time is your maintenance window. Also remember that the database user on Zenifra has no superuser access, but has enough elevated access to operate the database normally.
For the Key-Value Store, create a managed cache or a Key-Value database on Zenifra and replace REDIS_URL. Cache and session data are usually rebuilt by the application, so they do not need copying. If the Key-Value Store holds queues, such as Sidekiq or Celery queues, let the Heroku workers drain the queue before the switch, so no job is left behind.
# Backup through Heroku itself
heroku pg:backups:capture -a my-app
heroku pg:backups:download -a my-app # creates latest.dump
# Check that the file is intact
pg_restore --list latest.dump > /dev/null && echo "dump ok"
# Restore into Zenifra PostgreSQL
pg_restore --no-owner --no-acl --jobs=4 \
--dbname="postgresql://user:password@host:port/database?sslmode=require" \
latest.dump# Database over 20 GB: direct copy with pg_dump
heroku pg:credentials:url DATABASE -a my-app
pg_dump --format=custom --no-owner --no-acl "HEROKU_URL?sslmode=require" > dump.pgdumpThe Console URI ends with ?sslmode=require and works with any version of psql, pg_dump, and pg_restore, with no certificate file.
Step 5: cutover window, domain, DNS, and rollback
Before touching DNS, validate everything on the *.clients.zenifra.com URL the project receives: login, main flows, email sending, workers, and webhooks. Check Build logs and the application logs for errors. One day before the switch, lower the DNS record TTL to 300 seconds, so the change propagates quickly, and so would a rollback.
At the agreed time, turn on Heroku maintenance mode with heroku maintenance:on -a my-app to freeze writes, do the final database copy as in the previous step, and add the domain on Zenifra: open the project, click Edit, go to Custom domains, click Add, enter the domain, and click Save custom domains. The Configure custom domain DNS window shows the records to create at your DNS provider and the ones that must be deleted.
For a subdomain, such as www or app, the table shows a CNAME and the TXT validation records. For the apex domain, it shows a single A record on @, with no TXT; if your DNS is on Cloudflare, create the A record with the proxy off (DNS only). Do not keep an AAAA or a second A record on @, and do not remove and re-add the same domain to see the records again, because the TXT values change with each registration: use View DNS setup. The HTTPS certificate is issued automatically once DNS is correct, and each project accepts up to 20 custom domains.
Keep the Heroku app running for a few days. That is your platform rollback: if something serious shows up, point DNS back to the targets heroku domains showed and turn maintenance mode off. Data written on Zenifra after the switch has to go back to Heroku with the same pg_dump and pg_restore, in the opposite direction. Version rollback inside Zenifra is not automatic: in Automatic by branch projects, make a revert commit or deploy a stable commit with zenifra deploy --project <project-id> --commit-sha <sha> or with New build in Build logs. Keep in mind that rolling back code does not undo database migrations.
Final checklist and common errors after the migration
The checklist below combines the cutover-day checklist from the docs with the Heroku-specific points. Go through it during the rehearsal and again on cutover day; almost every migration problem shows up in the rehearsal, when it still costs nothing.
The common errors table brings together the symptoms listed in the Heroku migration guide and two that often appear for people coming from other platforms: the PostgreSQL connection limit and the old database URI, copied before the switch to sslmode=require.
- DNS TTL lowered to 300 seconds one day in advance.
- Application validated on the
*.clients.zenifra.comURL, including workers, emails, and webhooks. - Variables reviewed, with no Heroku URLs, and
PORTequal to the Port field. - Migrations run at the beginning of the Start Command or manually, before the version that depends on them.
- One private project for each process other than
web, and one Scheduled job for each Scheduler task. - External webhooks (payments, GitHub, email) updated to the new domain.
- Final data copy finished and validated with row counts.
- Domain configured and HTTPS active.
- Heroku app kept running for a few days; then dynos turned off and add-ons removed to stop billing.
| Symptom | Likely cause | Fix |
|---|---|---|
npm ci fails | App uses Yarn or pnpm, with no package-lock.json | Generate and commit a package-lock.json |
| Python build does not install dependencies | Project uses Poetry, uv, or Pipenv | Export a requirements.txt |
| Public URL does not respond | App listens on localhost or on another port | Listen on 0.0.0.0, on the Port field value, and set PORT |
| Tables do not exist | The release phase does not run on Zenifra | Run migrations in the Start Command or manually |
| Background tasks stopped | Worker was not created | Create a private project for each process other than web |
Missing assets or staticfiles | The buildpack ran that step on its own | Put collectstatic or assets:precompile in the Build Command |
remaining connection slots are reserved | Connection pool above the plan limit (15 on DB-Starter, 72 on DB-Basic, 147 on DB-Premium) | Cap the pool, adding up all application instances |
ENOENT system error with pg in Node.js | Old URI, with sslrootcert=system | Copy the URI again from the Console; it ends with ?sslmode=require |
Do I need to change my code to leave Heroku?
Usually not. Zenifra deploys the same GitHub (or Forgejo) repository or a Docker image, and the changes usually live in the project configuration, not in the code. The most common ones are listening on 0.0.0.0 on the port set in Port, reading the new DATABASE_URL, and moving the migration from the release phase to the Start Command.
In Node.js, commit a package-lock.json if the app uses Yarn or pnpm, and move what the heroku-postbuild scripts did into the Build Command. In Python, export a requirements.txt if the project uses Poetry, uv, or Pipenv. For Ruby and .NET, the path is a Docker image. If your application uses pg in Node.js, the Console URI works with no change.
What happens to the Heroku release phase on Zenifra?
There is no equivalent step, so the release: line in the Procfile becomes one of two things: the beginning of the Start Command, such as npx prisma migrate deploy && npm start, or a manual step you run from your machine against the Zenifra database before deploying the version that depends on the migration.
In the Start Command, the command runs every time an instance starts, so it must be idempotent, and with several instances all of them run it: prefer migration tools that lock the database. For long or destructive migrations, the manual step is the safest, and it is worth following the rollback docs: migrations compatible with two versions of the application, tested first in a separate environment.
Does Heroku Scheduler have an equivalent on Zenifra?
Yes: each Scheduler task becomes a Scheduled job, created with GitHub Repository as the Task source, the same Runtime as the app, the command in Task command, and a five-field Cron expression in UTC. Since both platforms use UTC, "every day at 06:00" becomes 0 6 * * * with no time zone conversion.
The difference is that a Job accepts any cron expression, such as 0 9 * * 1-5 for weekdays, while Scheduler offers fixed frequencies. A Job is billed per minute of execution, in reais, and has clear rules: one execution at a time, a 60-minute limit, and no automatic retry when it fails. If the task needs retries, handle that in the code itself or with a queue.
How long is the application down during the switch?
Only for the final database copy, because the application is already deployed and validated on Zenifra before the switch. During that interval, Heroku maintenance mode freezes writes, and the domain keeps answering with the maintenance page.
That time depends on the database size and on how much pg_restore --jobs=4 can parallelize, and the only reliable way to know is the full rehearsal the docs recommend. With the DNS TTL at 300 seconds, propagation of the switch is short as well. If the rehearsal shows a window that is too long for your business, talk to support before setting a date.
Can I rehearse the migration first and pay with PIX?
Yes. With hourly billing, the rehearsal costs only the hours the projects are running: Basic costs R$0.05 per hour and DB-Starter R$0.018 per hour, plus R$0.20 per GB of disk per month. Credit is added by PIX, from R$5, or boleto, from R$30. Sign-up asks for a CPF or CNPJ, a mobile number, and an address in Brazil. You can deploy the app from GitHub, restore a copy of the Heroku database, and validate the main flows before switching the domain.
An 8-hour rehearsal with Basic and DB-Starter costs R$0.544, plus disk, and billing is in reais, by PIX, boleto, or card, without IOF.