> ## 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.**](/core-concepts/security-compliance/overview)
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
If you're migrating from standard Heroku (not Shield), see the [general Heroku migration guide](/how-to-guides/platform-guides/heroku-migration).
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
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.
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](/reference/pricing).
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](/how-to-guides/app-guides/define-services#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 using [Direct Docker Image Deploy](/how-to-guides/app-guides/migrate-dockerfile-to-direct-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`](/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](/core-concepts/architecture/stacks)) |
| **Developer Experience** | | |
| Runtime Model | Dynos | [Docker containers](/core-concepts/architecture/containers/overview) |
| Build System | Buildpacks | Dockerfile-based |
| Traffic Routing | Heroku Router | Explicit [Endpoints](/core-concepts/apps/connecting-to-apps/app-endpoints/overview) |
| 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](/core-concepts/apps/connecting-to-apps/app-endpoints/overview) supported) |
| Managed Databases | Shield Postgres & Shield Redis | [PostgreSQL](/core-concepts/managed-databases/supported-databases/postgresql), [MySQL](/core-concepts/managed-databases/supported-databases/mysql), [Redis](/core-concepts/managed-databases/supported-databases/redis), [Elasticsearch](/core-concepts/managed-databases/supported-databases/elasticsearch), [RabbitMQ](/core-concepts/managed-databases/supported-databases/rabbitmq), [InfluxDB](/core-concepts/managed-databases/supported-databases/influxdb), [SFTP](/core-concepts/managed-databases/supported-databases/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](/core-concepts/architecture/containers/overview) | A running instance of your application process |
| Heroku Router | [Endpoint](/core-concepts/apps/connecting-to-apps/app-endpoints/overview) | Network entry point that routes traffic to your service |
| App URL | Endpoint URL | Public hostname exposing your service |
| Private Space | [Dedicated Stack](/core-concepts/architecture/stacks) | Isolated infrastructure environment |
| Project | [Environment](/core-concepts/architecture/environments) | Logical grouping of apps and databases |
| Config Vars | [Environment Variables](/core-concepts/apps/deploying-apps/configuration) | Runtime configuration values |
| Buildpacks | Dockerfile | Defines how your application is built |
| Shield Postgres | [Managed PostgreSQL](/core-concepts/managed-databases/supported-databases/postgresql) | Production database service |
| Shield Redis | [Managed Redis](/core-concepts/managed-databases/supported-databases/redis) | In-memory data store |
| Add-ons | [Managed Databases](/core-concepts/managed-databases/overview) or External Integrations | Infrastructure services attached to your app |
## Before you begin
Before starting your migration from Heroku Shield, ensure the following:
[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.
The CLI allows you to deploy applications, manage databases, and interact with your environment directly from your terminal.
[Install the CLI here](/reference/aptible-cli/overview).
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**](/core-concepts/architecture/stacks). A Dedicated Stack is an isolated AWS environment with its own VPC, enforced encryption, and infrastructure-level security controls.
Create a Dedicated Stack in the appropriate region. Dedicated Stacks are required for [HIPAA compliance](/how-to-guides/platform-guides/hipaa-compliance).
During Stack provisioning, Aptible Support will coordinate execution of your Business Associate Agreement if you are handling PHI.
Confirm IP allowlists, outbound access, and any required third-party integrations. See [Network Integrations](/core-concepts/integrations/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**](/core-concepts/architecture/environments), 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](/core-concepts/architecture/containers/overview). 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](/core-concepts/apps/deploying-apps/services) |
| Dyno scaling | Container scaling |
| Release phase | Explicit release command via [.aptible.yml](/core-concepts/apps/deploying-apps/releases/aptible-yml) |
If your app does not already use Docker, create a `Dockerfile`. See [Getting Started with Docker](/how-to-guides/app-guides/getting-started-with-docker) 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
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](/core-concepts/apps/deploying-apps/releases/aptible-yml) in `.aptible.yml`
Each service can be scaled independently.
Procfile and `.aptible.yml` placement depends on your deployment method:
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`](/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy) for details.
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](/core-concepts/apps/deploying-apps/configuration) for more details.
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](/core-concepts/scaling/app-scaling) for guidance.
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](/core-concepts/managed-databases/supported-databases/postgresql), [Redis](/core-concepts/managed-databases/supported-databases/redis), as well as [MySQL](/core-concepts/managed-databases/supported-databases/mysql), [Elasticsearch](/core-concepts/managed-databases/supported-databases/elasticsearch), [InfluxDB](/core-concepts/managed-databases/supported-databases/influxdb), [RabbitMQ](/core-concepts/managed-databases/supported-databases/rabbitmq), and [SFTP](/core-concepts/managed-databases/supported-databases/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.
```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
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](/core-concepts/managed-databases/supported-databases/postgresql) for supported versions and extensions.
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](/how-to-guides/database-guides/dump-restore-postgresql) for detailed instructions.
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.
* 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
Logical replication keeps your Aptible database in sync with your Heroku database until you cut over. This minimizes downtime for high-traffic production applications.
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](/core-concepts/managed-databases/supported-databases/postgresql) for supported versions.
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](/core-concepts/managed-databases/managing-databases/replication-clustering) and [`aptible db:replicate`](/reference/aptible-cli/cli-commands/cli-db-replicate) for details.
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.
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
Create a managed Redis instance:
```bash theme={null}
aptible db:create your-redis \
--type redis \
--environment your-environment
```
Confirm version compatibility. See [Redis documentation](/core-concepts/managed-databases/supported-databases/redis).
Update the environment variable in Aptible:
```bash theme={null}
aptible config:set --app your-app-name REDIS_URL=redis://...
```
If Redis is used as:
* **Cache only**: No data migration required
* **Job queue**: Coordinate cutover carefully to avoid dropped jobs
* 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](/core-concepts/managed-databases/supported-databases/postgresql) |
| Shield Redis | Migrate to [Aptible-managed Redis](/core-concepts/managed-databases/supported-databases/redis) |
| Logging add-ons (e.g., Papertrail) | Configure [log drains](/core-concepts/observability/logs/log-drains/overview) 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**](/core-concepts/apps/connecting-to-apps/app-endpoints/overview).
#### Public Endpoints
If your application is publicly accessible:
* Create a Public Endpoint for the service
* Attach your [custom domain](/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain)
* Confirm [TLS configuration](/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls)
* Validate [IP allowlists](/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) 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](/core-concepts/apps/connecting-to-apps/outbound-ips)
* 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 your application in Aptible staging. Perform database migration to staging and test thoroughly.
Lower DNS TTL at least 24 hours before cutover to enable faster DNS propagation.
Schedule a maintenance window if required for your application.
Take a final database backup immediately before cutover:
```bash theme={null}
heroku pg:backups:capture --app your-app-name
```
Restore the final backup to your Aptible production database.
Update environment variables to point to the new database.
Switch DNS to the Aptible Endpoint.
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](https://app.aptible.com/support). White-glove migration services are also available for teams seeking hands-on assistance.