> ## 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 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.**](/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 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](/how-to-guides/platform-guides/heroku-shield-migration) for Shield-specific guidance.
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 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.
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](/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 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](/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 | Heroku Postgres & 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 | 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](/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 |
| Heroku Postgres | [Managed PostgreSQL](/core-concepts/managed-databases/supported-databases/postgresql) | Production database service |
| Heroku 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, 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.
* **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](/how-to-guides/platform-guides/hipaa-compliance).
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).
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**](/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. If you need to support [HIPAA compliance](/how-to-guides/platform-guides/hipaa-compliance), Dedicated Stacks are required.
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 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**](/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
#### 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](/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 | 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 provides Heroku Postgres and Heroku Redis.
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
### Audit your add-ons
Before migrating, review all add-ons attached to your Heroku application:
```bash theme={null}
heroku addons --app your-app-name
```
Typical mappings:
| Heroku Add-on | Migration Approach |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Heroku Postgres | Migrate to [Aptible-managed PostgreSQL](/core-concepts/managed-databases/supported-databases/postgresql) |
| Heroku 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 |
### Configure endpoints and networking
In Heroku, applications are exposed via the Heroku Router.
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 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.
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 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](https://app.aptible.com/support) is available to help. White-glove migration services are also available for teams that want hands-on assistance.