Heroku Shield to Aptible Migration Guide

A comprehensive guide for migrating compliance-focused applications from Heroku Shield to Aptible

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 deploying via Docker image (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 when deploying via Docker image 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:

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.

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

1. Provision a Dedicated Stack

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

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 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

1. 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
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:

   Deploying via Git

   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.

   Deploying via Docker image

   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 when deploying via Docker image 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 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)

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

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.

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