> ## Documentation Index
> Fetch the complete documentation index at: https://www.aptible.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.**](https://www.aptible.com/docs/core-concepts/security-compliance/overview.md)

If you are evaluating alternatives due to[ recent changes to Heroku’s Enterprise offering](https://www.heroku.com/blog/an-update-on-heroku/), 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

> [!TIP]
>
> If you're migrating from standard Heroku (not Shield), see the [general Heroku migration guide](https://www.aptible.com/docs/how-to-guides/platform-guides/heroku-migration.md).

> [!TIP]
>
> If you require further assistance or guidance during your migration, please [contact Aptible Support](https://app.aptible.com/support). White-glove migration services are also available for teams that want hands-on assistance.

## FAQs

> [accordion] 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.

> [accordion] 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](https://www.aptible.com/docs/reference/pricing.md).

> [accordion] 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](https://www.aptible.com/docs/how-to-guides/app-guides/define-services.md#how-to-define-services).
>
> 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](https://www.aptible.com/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy.md) (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`](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-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](https://www.aptible.com/docs/core-concepts/architecture/stacks.md)) |
| **Developer Experience** | | |
| Runtime Model | Dynos | [Docker containers](https://www.aptible.com/docs/core-concepts/architecture/containers/overview.md) |
| Build System | Buildpacks | Dockerfile-based |
| Traffic Routing | Heroku Router | Explicit [Endpoints](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview.md) |
| 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](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview.md) supported) |
| Managed Databases | Shield Postgres & Shield Redis | [PostgreSQL](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/postgresql.md), [MySQL](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/mysql.md), [Redis](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/redis.md), [Elasticsearch](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/elasticsearch.md), [RabbitMQ](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/rabbitmq.md), [InfluxDB](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/influxdb.md), [SFTP](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/sftp.md) |
| **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](https://www.aptible.com/docs/core-concepts/architecture/containers/overview.md) | A running instance of your application process |
| Heroku Router | [Endpoint](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview.md) | Network entry point that routes traffic to your service |
| App URL | Endpoint URL | Public hostname exposing your service |
| Private Space | [Dedicated Stack](https://www.aptible.com/docs/core-concepts/architecture/stacks.md) | Isolated infrastructure environment |
| Project | [Environment](https://www.aptible.com/docs/core-concepts/architecture/environments.md) | Logical grouping of apps and databases |
| Config Vars | [Environment Variables](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/configuration.md) | Runtime configuration values |
| Buildpacks | Dockerfile | Defines how your application is built |
| Shield Postgres | [Managed PostgreSQL](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/postgresql.md) | Production database service |
| Shield Redis | [Managed Redis](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/redis.md) | In-memory data store |
| Add-ons | [Managed Databases](https://www.aptible.com/docs/core-concepts/managed-databases/overview.md) 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](https://app.aptible.com/signup) 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](https://www.aptible.com/docs/reference/aptible-cli/overview.md).

**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**](https://www.aptible.com/docs/core-concepts/architecture/stacks.md). 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](https://www.aptible.com/docs/how-to-guides/platform-guides/hipaa-compliance.md).

**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](https://www.aptible.com/docs/core-concepts/integrations/network-integrations.md) for fVPN and VPC peering options.

> [!NOTE]
>
> 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**](https://www.aptible.com/docs/core-concepts/architecture/environments.md), 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

> [!TIP]
>
> 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](https://www.aptible.com/docs/core-concepts/architecture/containers/overview.md). 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](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/services.md) |
| Dyno scaling | Container scaling |
| Release phase | Explicit release command via [.aptible.yml](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/releases/aptible-yml.md) |

**1. Convert Buildpack App to Docker**

If your app does not already use Docker, create a `Dockerfile`. See [Getting Started with Docker](https://www.aptible.com/docs/how-to-guides/app-guides/getting-started-with-docker.md) for guidance.

Example (Node.js):

```dockerfile theme={null}
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](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/releases/aptible-yml.md) in `.aptible.yml`

Each service can be scaled independently.

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

> [tab] 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.

> [tab] 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`](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy) for details.

**3. Configure environment variables**

Export your current Heroku variables:

```bash theme={null}
heroku config --app your-app-name
```

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

```bash theme={null}
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](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/configuration.md) 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.

```bash theme={null}
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](https://www.aptible.com/docs/core-concepts/scaling/app-scaling.md) 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](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/postgresql.md), [Redis](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/redis.md), as well as [MySQL](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/mysql.md), [Elasticsearch](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/elasticsearch.md), [InfluxDB](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/influxdb.md), [RabbitMQ](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/rabbitmq.md), and [SFTP](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/sftp.md).

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

> [!TIP]
>
> 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.

> [accordion] Option A: Dump and Restore (recommended for databases under 10GB)
>
> **1. Capture backup from Heroku**
>
> ```bash theme={null}
> 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:
>
> ```bash theme={null}
> 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](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/postgresql.md) for supported versions and extensions.
>
> **3. Restore database**
>
> Open a tunnel to your new database:
>
> ```bash theme={null}
> aptible db:tunnel your-database --environment your-environment
> ```
>
> In a separate terminal, restore the backup:
>
> ```bash theme={null}
> 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](https://www.aptible.com/docs/how-to-guides/database-guides/dump-restore-postgresql.md) for detailed instructions.
>
> **4. Update DATABASE\_URL**
>
> Replace Heroku credentials with the Aptible database credentials:
>
> ```bash theme={null}
> 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

> [accordion] 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:
>
> ```bash theme={null}
> aptible db:create your-database \
>   --type postgresql \
>   --version 16 \
>   --environment your-environment
> ```
>
> Match the PostgreSQL version to your Heroku database. See [PostgreSQL documentation](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/postgresql.md) for supported versions.
>
> **2. Set up logical replication**
>
> Use the Aptible CLI to create a logical replica that syncs from your Heroku database:
>
> ```bash theme={null}
> 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](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/replication-clustering.md) and [`aptible db:replicate`](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-replicate) for details.
>
> **3. Monitor replication status**
>
> Verify that all tables have finished the initial sync:
>
> ```sql theme={null}
> 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:

```bash theme={null}
aptible db:create your-redis \
  --type redis \
  --environment your-environment
```

Confirm version compatibility. See [Redis documentation](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/redis.md).

**2. Update REDIS\_URL**

Update the environment variable in Aptible:

```bash theme={null}
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:

```bash theme={null}
heroku addons --app your-app-name
```

Typical mappings:

| Heroku Add-on | Migration Approach |
| - | - |
| Shield Postgres | Migrate to [Aptible-managed PostgreSQL](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/postgresql.md) |
| Shield Redis | Migrate to [Aptible-managed Redis](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/redis.md) |
| Logging add-ons (e.g., Papertrail) | Configure [log drains](https://www.aptible.com/docs/core-concepts/observability/logs/log-drains/overview.md) 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**](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview.md).

#### Public Endpoints

If your application is publicly accessible:

* Create a Public Endpoint for the service
* Attach your [custom domain](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain.md)
* Confirm [TLS configuration](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls.md)
* Validate [IP allowlists](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering.md) 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](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/outbound-ips.md)
* Confirm third-party allowlists
* Update webhook destinations if needed
* Verify internal service-to-service communication

> [!NOTE]
>
> 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:

```bash theme={null}
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.

> [!WARNING]
>
> **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](https://app.aptible.com/support). White-glove migration services are also available for teams seeking hands-on assistance.