Heroku Shield to Aptible Migration Guide

Overview

If you are searching for a Heroku Shield alternative, Aptible is one of the strongest platform-as-a-service options to evaluate, and for many regulated teams, the most natural fit. Aptible delivers a similar developer experience with simple, abstracted deployment of apps and databases, while providing dedicated infrastructure isolation, enforced security controls, and built-in compliance support for frameworks such as HIPAA, HITRUST, and SOC 2. For teams handling PHI or other sensitive data, these controls are foundational, not optional. 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 that previously relied on Heroku Shield for HIPAA-eligible environments are now looking for infrastructure that combines developer simplicity with robust security and compliance support. This guide will help you evaluate Aptible and outline a clear path for a smooth migration, including:

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

If you’re migrating from standard Heroku (not Shield), see the general Heroku migration guide.

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 Shield to Aptible?

Aptible is a security, compliance, and reliability-focused platform as a service (PaaS). Migrating to Aptible enables you to maintain a strong compliance posture with built-in support for frameworks such as HIPAA, HITRUST, and SOC 2, while gaining more flexibility in pricing and operational control.Teams typically migrate from Heroku Shield when they need HITRUST inheritance, more flexible pricing, or want to avoid 12-month contract commitments while maintaining the same level of compliance.

How does Aptible pricing compare to Heroku Shield?

If you’re migrating from Heroku Shield, 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.Aptible’s pricing model is usage-based with simple line items and no long-term lock-ins or steep minimums.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 Shield vs Aptible comparison

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

Category	Heroku Shield	Aptible
Compliance
HIPAA Eligibility	Included	Included
HITRUST Inheritance	Not available	Included
BAA Support	Included	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	Shield Postgres & Shield Redis	PostgreSQL, MySQL, Redis, Elasticsearch, RabbitMQ, InfluxDB, SFTP
Pricing
Compute Pricing Model	Shield dyno tiers	Container-based pricing
Isolation Cost	High fees for getting started	Low fees for getting started: $499/base fee
Contract	12-month contract required	Pay-as-you-go, no lock-in
White-glove migration	Not available	Available with additional fee

Key terminology mapping

If you’re migrating from Heroku Shield, 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
Shield Postgres	Managed PostgreSQL	Production database service
Shield 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 from Heroku Shield, ensure the following:

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.

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.

Review your existing Heroku Shield setup

Ensure you have access to your Heroku app, Private Space, and Shield Postgres credentials. Make note of the following:

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 Shield, applications 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.

Provision a Dedicated Stack

Create a Dedicated Stack in the appropriate region. Dedicated Stacks are required for HIPAA compliance.

Execute a BAA if required

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

Review networking requirements

Confirm IP allowlists, outbound access, and any required third-party integrations. See Network Integrations for fVPN 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

Choose the approach that aligns with your compliance and isolation requirements.

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

Shield Dynos to Containers

In Heroku Shield, 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 Shield	Aptible
Buildpacks	Dockerfile
Procfile process types	Separate services
Dyno scaling	Container scaling
Release phase	Explicit release command via .aptible.yml

Convert Buildpack App to Docker

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

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)
Direct Docker Image 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.

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.

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.

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.

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 Shield provides Shield Postgres and Shield Redis inside your Private Space with encryption and compliance controls. 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)

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

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.

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.

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.

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.

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.

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.

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.

Cut over

When ready to cut over:

Stop writes to the Heroku database
Verify replication is caught up
Update DATABASE_URL to point to Aptible
Switch DNS to Aptible

Migrating Redis

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.

Update REDIS_URL

Update the environment variable in Aptible:

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

Plan cutover

If Redis is used as:

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

Validate

Confirm application connectivity
Monitor background worker logs
Validate job processing

Auditing your add-ons

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

heroku addons --app your-app-name

Typical mappings:

Heroku Add-on	Migration Approach
Shield Postgres	Migrate to Aptible-managed PostgreSQL
Shield 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

Configuring endpoints and networking

In Heroku Shield, applications are exposed via the Heroku Router within a Private Space. 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 from Shield to a dedicated infrastructure model. Take time to review your requirements carefully.

Minimizing downtime during cutover

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

Deploy and validate in staging

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

Lower DNS TTL

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

Schedule maintenance window

Schedule a maintenance window if required for your application.

Take final backup

Take a final database backup immediately before cutover:

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

Restore final backup

Restore the final backup to your Aptible production database.

Update environment variables

Update environment variables to point to the new database.

Switch DNS

Switch DNS to the Aptible Endpoint.

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 Shield resources.

Closing thoughts

For most teams, migrating from Heroku Shield to Aptible is a same-day process. The core steps are mapping your infrastructure, migrating your databases, and executing a cutover strategy with minimal disruption. Once complete, your regulated workloads run on a platform designed for security and compliance. If you need guidance during your migration, contact Aptible Support. White-glove migration services are also available for teams seeking hands-on assistance.

How to Guides

Troubleshooting

Heroku Shield to Aptible Migration Guide

Overview

FAQs

Heroku Shield vs Aptible comparison

Key terminology mapping

Before you begin

Migration steps

Set up your Aptible infrastructure

Private Spaces to Dedicated Stacks

Projects to Environments

Migrate your application

Shield Dynos to Containers

Migrate your databases

Migrating PostgreSQL

Migrating Redis

Auditing your add-ons

Configuring endpoints and networking

Public Endpoints

Private Endpoints

Networking checklist

Minimizing downtime during cutover

Closing thoughts

How to Guides

Troubleshooting

​Overview

​FAQs

​Heroku Shield vs Aptible comparison

​Key terminology mapping

​Before you begin

​Migration steps

​Set up your Aptible infrastructure

​Private Spaces to Dedicated Stacks

​Projects to Environments

​Migrate your application

​Shield Dynos to Containers

​Migrate your databases

​Migrating PostgreSQL

​Migrating Redis

​Auditing your add-ons

​Configuring endpoints and networking

​Public Endpoints

​Private Endpoints

​Networking checklist

​Minimizing downtime during cutover

​Closing thoughts

Overview

FAQs

Heroku Shield vs Aptible comparison

Key terminology mapping

Before you begin

Migration steps

Set up your Aptible infrastructure

Private Spaces to Dedicated Stacks

Projects to Environments

Migrate your application

Shield Dynos to Containers

Migrate your databases

Migrating PostgreSQL

Migrating Redis

Auditing your add-ons

Configuring endpoints and networking

Public Endpoints

Private Endpoints

Networking checklist

Minimizing downtime during cutover

Closing thoughts