Heroku to Aptible Migration Guide

A comprehensive guide for migrating applications from Heroku to Aptible

Overview

If you are searching for a Heroku alternative, particularly a Heroku Enterprise alternative, Aptible is one of the strongest platform-as-a-service options to evaluate. For teams that need a Heroku-like developer experience but stronger security, isolation, and compliance foundations, Aptible is a natural next step.

Aptible offers simple, abstracted deployment of apps, databases, and infrastructure while providing dedicated infrastructure isolation, enforced security controls, and built-in compliance support for frameworks such as HIPAA, HITRUST, and SOC 2. These capabilities are especially important for startups operating in regulated industries and enterprise teams with strict security, reliability, and audit requirements.

Refer to the Security & Compliance docs for more information on our approach to security and compliance, including the specific controls we satisfy.

If you are evaluating alternatives due to recent changes to Heroku’s Enterprise offering, you’re in the right place. Many teams are reassessing their infrastructure strategy and looking for a platform that preserves developer velocity while strengthening security, compliance posture, and operational control.

This guide will help you both evaluate Aptible and outline a clear path for a smooth migration, including:

• Heroku vs Aptible comparison
• Key terminology mapping
• Technical migration steps:
  • Private Spaces to Dedicated Stacks
  • Projects to Environments
  • Dynos to containers
  • Heroku Postgres and Redis to Aptible-managed databases
  • Auditing add-ons
  • Reconfiguring endpoints and networking
  • Minimizing downtime during cutover

Migrating from Heroku Shield? If you’re currently running compliance-focused workloads on Heroku Shield and handling regulated data such as PHI, see the Heroku Shield to Aptible Migration Guide for Shield-specific guidance.

If you require further assistance or guidance during your migration, please contact Aptible Support. White-glove migration services are also available for teams that want hands-on assistance.

FAQs

Why migrate from Heroku to Aptible?

Aptible is a security, compliance, and reliability-focused platform as a service (PaaS). Migrating to Aptible enables you to instantly adopt a stronger security and compliance posture, with built-in support for frameworks such as HIPAA, HITRUST, and SOC 2, while maintaining the ease of use and developer experience you may already be familiar with from Heroku.

Teams typically migrate to Aptible when they need more robust security controls, stronger compliance guarantees, or higher reliability, without taking on the operational burden of managing their own infrastructure.

How does Aptible pricing compare to Heroku?

If you’re coming from Heroku’s standard platform, Aptible’s pricing model will feel familiar: usage-based billing, simple line items, and no long-term lock-ins or steep minimums.

If you’re migrating from Heroku Enterprise or Shield specifically, Aptible differs in two important ways: Aptible does not require a 12-month contract, and Aptible does not enforce high minimum spend thresholds. This makes it easier to adopt without long-term financial commitments.

Learn more about pricing.

Can I keep using a Procfile?

Yes. Heroku requires a Procfile to define application processes, but on Aptible, Procfiles are optional.

If no Procfile is present, Aptible will infer the service command from the Dockerfile CMD instruction. This is referred to as an Implicit Service.

You can continue using a Procfile if your application has multiple services or process types. Procfile syntax is compatible between Heroku and Aptible.

Note: If you are using Direct Docker Image Deploy (deploying a pre-built image from a container registry), you must place your Procfile at /.aptible/Procfile and your .aptible.yml at /.aptible/.aptible.yml inside your Docker image. See Procfiles and .aptible.yml with Direct Docker Image Deploy for details.

Heroku vs Aptible comparison

The table below summarizes key differences across compliance, developer experience, and pricing.

Category	Heroku	Aptible
Compliance
HIPAA Eligibility	Available (Enterprise/Shield)	Included
HITRUST Inheritance	Not available	Included
BAA Support	Available (Enterprise/Shield)	Included
Encryption in Transit and at Rest	Included	Included, by default
Managed Intrusion Detection	Not available	Included, by default
24/7 SRE Monitoring	Available with additional fee	Included, by default
Automated Backups	Included, plan-dependent retention	Included, by default
Granular Access Control	Limited	Included, by default
Infrastructure Isolation	Included (Private Spaces)	Included (Dedicated Stacks)
Developer Experience
Runtime Model	Dynos	Docker containers
Build System	Buildpacks	Dockerfile-based
Traffic Routing	Heroku Router	Explicit Endpoints
Automatic Rollbacks	Limited	Included, by default
Zero-downtime deploys	Included, by default	Included, by default
Public and Private Access	Limited	Available (Public and Private Endpoints supported)
Managed Databases	Heroku Postgres & Redis	PostgreSQL, MySQL, Redis, Elasticsearch, RabbitMQ, InfluxDB, SFTP
Pricing
Compute Pricing Model	Dyno tiers	Container-based pricing
Contract	12-month contract (Enterprise)	Pay-as-you-go, no lock-in

Key terminology mapping

If you’re migrating from Heroku, the table below maps common Heroku concepts to their Aptible equivalents.

Heroku Term	Aptible Term	Description
Dyno	Container	A running instance of your application process
Heroku Router	Endpoint	Network entry point that routes traffic to your service
App URL	Endpoint URL	Public hostname exposing your service
Private Space	Dedicated Stack	Isolated infrastructure environment
Project	Environment	Logical grouping of apps and databases
Config Vars	Environment Variables	Runtime configuration values
Buildpacks	Dockerfile	Defines how your application is built
Heroku Postgres	Managed PostgreSQL	Production database service
Heroku Redis	Managed Redis	In-memory data store
Add-ons	Managed Databases or External Integrations	Infrastructure services attached to your app

Before you begin

Before starting your migration, ensure the following:

1. Create an Aptible account

   Sign up for Aptible to get started with a 30-day free trial. When you’re ready to begin your production migration, upgrade to the Production plan.

   • Development is intended for early-stage development and testing, when you do not yet have production security or compliance requirements.
   • Production is designed for production workloads and provides access to highly secure and compliant resources, including support for frameworks such as HIPAA.
2. Install the Aptible CLI

   The CLI allows you to deploy applications, manage databases, and interact with your environment directly from your terminal.

   Install the CLI here.

3. Review your existing Heroku setup

   Before migrating, make note of the following details from your existing Heroku setup:

   • Application process types (web, worker, background jobs)
   • Environment variables and secrets
   • Add-ons such as databases, caches, or third-party services
   • Any custom build or runtime configuration
   • Networking or domain configuration

Migration steps

Set up your Aptible infrastructure

Private Spaces to Dedicated Stacks

In Heroku, applications can run inside Private Spaces, which define the network boundary and isolation model for your workloads.

In Aptible, the equivalent concept is a Dedicated Stack. A Dedicated Stack is an isolated AWS environment with its own VPC, enforced encryption, and infrastructure-level security controls.

1. Provision a Dedicated Stack

   Create a Dedicated Stack in the appropriate region. If you need to support HIPAA compliance, Dedicated Stacks are required.

2. Execute a BAA if required

   During Stack provisioning, Aptible Support will coordinate execution of your Business Associate Agreement if you are handling PHI.

3. Review networking requirements

   Confirm IP allowlists, outbound access, and any required third-party integrations. See Network Integrations for VPN and VPC peering options.

If you currently use multiple Private Spaces for staging and production, you can either:

• Create separate Environments within a single Dedicated Stack (most common approach)
• Provision multiple Dedicated Stacks if stricter infrastructure separation is required

Projects to Environments

In Heroku, applications are grouped into Projects and can be connected via Pipelines.

In Aptible, applications and databases are grouped within an Environment, which exists inside a Dedicated Stack. An Environment provides logical separation between staging and production workloads and defines access controls.

• Create an Environment corresponding to each Heroku Project
• Create separate Environments for staging and production

Granular user access is assigned at the Environment level. For example, you can grant full access to a staging Environment while restricting permissions in production.

Migrate your application

Dynos to Containers

In Heroku, applications run as dynos built via buildpacks and defined by a Procfile. Heroku manages the runtime layer and abstracts containerization.

In Aptible, applications run as Docker containers. You define how the application is built and executed using a Dockerfile, and each process type runs as its own service.

Key differences:

Heroku	Aptible
Buildpacks	Dockerfile
Procfile process types	Separate services
Dyno scaling	Container scaling
Release phase	Explicit release command via .aptible.yml

1. Add a Dockerfile

   If your app does not already use Docker, create a Dockerfile. See Getting Started with Docker for guidance.

   Example (Node.js):

   FROM node:18
   
   WORKDIR /app
   COPY package*.json ./
   RUN npm install
   
   COPY . .
   EXPOSE 3000
   CMD ["npm", "start"]
   

   Important checks:

   • App binds to 0.0.0.0
   • Correct port exposed
   • No reliance on ephemeral filesystem storage
2. Translate Procfile process types

   Typical Heroku Procfile:

   web: bundle exec rails server
   worker: bundle exec sidekiq
   release: bundle exec rails db:migrate
   

   In Aptible:

   • Deploy web as one service
   • Deploy worker as a separate service
   • Run database migrations using before_release in .aptible.yml

   Each service can be scaled independently.

   Procfile and .aptible.yml placement depends on your deployment method:

   Git Push (Dockerfile Deploy)

   If you deploy by pushing code to Aptible’s Git remote, keep your Procfile and .aptible.yml in the repository root directory. Aptible will detect and use them automatically during the build process.

   Direct Docker Image Deploy

   If you deploy a pre-built image from a container registry, you must place these files inside the Docker image at:

   • /.aptible/Procfile
   • /.aptible/.aptible.yml

   See Procfiles and .aptible.yml with Direct Docker Image Deploy for details.

3. Configure environment variables

   Export your current Heroku variables:

   heroku config --app your-app-name
   

   Recreate them in the Aptible Environment using the Dashboard or CLI:

   aptible config:set --app your-app-name KEY=value
   

   Pay special attention to:

   • DATABASE_URL
   • REDIS_URL
   • SECRET_KEY_BASE
   • External service credentials

   See Configuration Variables for more details.

4. Scale containers

   Match your dyno configuration. If you previously ran 2 web dynos and 1 worker dyno, scale to 2 web containers and 1 worker container.

   aptible apps:scale --app your-app-name --container-count 2 SERVICE
   

   Monitor CPU and memory usage after deployment and adjust as needed. See App Scaling for guidance.

5. Validate deployment

   Confirm:

   • Application boots without errors
   • Logs are flowing
   • Health checks pass
   • Background jobs process correctly
   • No reliance on Heroku-specific environment assumptions

Migrate your databases

Heroku provides Heroku Postgres and Heroku Redis.

In Aptible, you can provision managed PostgreSQL, Redis, as well as MySQL, Elasticsearch, InfluxDB, RabbitMQ, and SFTP.

Migrating PostgreSQL

There are two primary approaches to migrating PostgreSQL databases:

• Dump and restore works well for smaller databases (under 10GB) and simpler migrations
• Logical replication is recommended for databases over 10GB or high-traffic production apps where minimizing downtime is critical

For databases larger than 10GB, heroku pg:backups can be slow and unreliable. Logical replication keeps your Aptible database in sync with Heroku until you’re ready to cut over, significantly reducing downtime.

Option A: Dump and Restore (recommended for databases under 10GB)

1. Capture backup from Heroku

   heroku pg:backups:capture --app your-app-name
   heroku pg:backups:download --app your-app-name
   

   For large databases:

   • Schedule a maintenance window
   • Consider putting the application in read-only mode
   • Lower DNS TTL in advance if planning cutover
2. Provision PostgreSQL in Aptible

   Create a managed PostgreSQL database in the target Environment:

   aptible db:create your-database \
     --type postgresql \
     --version 16 \
     --environment your-environment
   

   • Confirm version compatibility with Heroku Postgres
   • Verify required extensions are supported

   See PostgreSQL documentation for supported versions and extensions.

3. Restore database

   Open a tunnel to your new database:

   aptible db:tunnel your-database --environment your-environment
   

   In a separate terminal, restore the backup:

   pg_restore --verbose --clean --no-acl --no-owner \
     -h localhost \
     -p PORT \
     -U aptible \
     -d db \
     latest.dump
   

   For large restores, use --jobs=N for parallel restore.

   See Dump and Restore PostgreSQL for detailed instructions.

4. Update DATABASE_URL

   Replace Heroku credentials with the Aptible database credentials:

   aptible config:set --app your-app-name DATABASE_URL=postgresql://...
   

   Confirm SSL mode is correct and update connection pooling configuration if used.

5. Validate database

   • Compare row counts
   • Verify schema
   • Confirm extensions such as pgcrypto or uuid-ossp
   • Run the application against the staging database
   • Monitor logs for connection errors

Option B: Logical Replication (recommended for databases over 10GB)

Logical replication keeps your Aptible database in sync with your Heroku database until you cut over. This minimizes downtime for high-traffic production applications.

1. Provision PostgreSQL in Aptible

   Create a managed PostgreSQL database in the target Environment:

   aptible db:create your-database \
     --type postgresql \
     --version 16 \
     --environment your-environment
   

   Match the PostgreSQL version to your Heroku database. See PostgreSQL documentation for supported versions.

2. Set up logical replication

   Use the Aptible CLI to create a logical replica that syncs from your Heroku database:

   aptible db:replicate heroku-source-db aptible-replica \
     --logical --version 16
   

   This uses the pglogical extension to replicate data from Heroku to Aptible. The replica stays in sync until you’re ready to cut over.

   See Database Replication and aptible db:replicate for details.

3. Monitor replication status

   Verify that all tables have finished the initial sync:

   SELECT * FROM pglogical.local_sync_status WHERE NOT sync_status = 'r';
   

   An empty result means all tables are fully replicated.

4. Cut over

   When ready to cut over:

   1. Stop writes to the Heroku database
   2. Verify replication is caught up
   3. Update DATABASE_URL to point to Aptible
   4. Switch DNS to Aptible

Migrating Redis

1. Provision Redis in Aptible

   Create a managed Redis instance:

   aptible db:create your-redis \
     --type redis \
     --environment your-environment
   

   Confirm version compatibility. See Redis documentation.

2. Update REDIS_URL

   Update the environment variable in Aptible:

   aptible config:set --app your-app-name REDIS_URL=redis://...
   
3. Plan cutover

   If Redis is used as:

   • Cache only: No data migration required
   • Job queue: Coordinate cutover carefully to avoid dropped jobs
4. Validate

   • Confirm application connectivity
   • Monitor background worker logs
   • Validate job processing

Audit your add-ons

Before migrating, review all add-ons attached to your Heroku application:

heroku addons --app your-app-name

Typical mappings:

Heroku Add-on	Migration Approach
Heroku Postgres	Migrate to Aptible-managed PostgreSQL
Heroku Redis	Migrate to Aptible-managed Redis
Logging add-ons (e.g., Papertrail)	Configure log drains to your observability provider (no additional cost)
Email providers	Continue using external provider and update credentials
Third-party services	Reconfigure networking and environment variables

Configure endpoints and networking

In Heroku, applications are exposed via the Heroku Router.

In Aptible, applications are exposed through explicitly defined Endpoints.

Public Endpoints

If your application is publicly accessible:

• Create a Public Endpoint for the service
• Attach your custom domain
• Confirm TLS configuration
• Validate IP allowlists if required

Private Endpoints

If your Heroku Private Space uses internal routing between services:

• Create Private Endpoints inside the Dedicated Stack
• Update internal service URLs
• Confirm security group or access configuration

Networking checklist

• Review outbound IP requirements
• Confirm third-party allowlists
• Update webhook destinations if needed
• Verify internal service-to-service communication

Networking differences are often the largest architectural shift when moving to a dedicated infrastructure model. Take time to review your requirements carefully.

Minimize downtime during cutover

To reduce downtime and risk during migration, plan the final cutover carefully.

1. Deploy and validate in staging

   Deploy and validate your application in Aptible staging. Perform database migration to staging and test thoroughly.

2. Lower DNS TTL

   Lower DNS TTL at least 24 hours before cutover to enable faster DNS propagation.

3. Schedule maintenance window

   Schedule a maintenance window if required for your application.

4. Take final backup

   Take a final database backup immediately before cutover:

   heroku pg:backups:capture --app your-app-name
   
5. Restore final backup

   Restore the final backup to your Aptible production database.

6. Update environment variables

   Update environment variables to point to the new database.

7. Switch DNS

   Switch DNS to the Aptible Endpoint.

8. Monitor

   Monitor logs, performance, and background workers.

Additional considerations:

• If Redis is used as a job queue, pause workers before final backup
• Confirm no writes occur between final backup and DNS switch
• Keep the Heroku app available briefly as a fallback if necessary

After confirming stable traffic and application behavior, decommission your Heroku resources.

Closing thoughts

Once your migration is complete, your workloads run on a platform designed for security, compliance, and long-term scalability. By carefully planning your infrastructure mapping, database migration, and cutover strategy, you can transition with minimal disruption.

If you need guidance during your migration, Aptible Support is available to help. White-glove migration services are also available for teams that want hands-on assistance.