Coming from a PaaS
Map application hosting and managed services to Encore
A PaaS typically combines application hosting, managed infrastructure, and platform-specific services. Encore is a backend development platform: you define APIs and services with its TypeScript or Go SDK and declare the infrastructure they use in the same application code. Encore uses those declarations to build an application model of your services, APIs, resources, and their relationships.
Encore applications can run in your own AWS or GCP account through the Encore platform, or on Encore Cloud Hosting for development and preview environments, or as self-hosted Docker images.
An Encore service is an application-code boundary containing API endpoints and resource usage. Infrastructure primitives are resources, such as databases or Pub/Sub topics, declared through the SDK. The table below links to TypeScript examples; equivalent primitives are available in Go.
How the concepts map
| PaaS concept | Encore equivalent |
|---|---|
| Application or service | An Encore application containing one or more services |
| Managed Postgres | A SQL database primitive |
| Redis or managed cache | A cache for supported operations, or an external Redis service |
| Object storage | An object storage bucket primitive |
| Event-driven asynchronous work | Pub/Sub topics and subscriptions |
| Scheduled jobs | Cron jobs |
| Secret environment variables | Secrets with values set per environment |
| Non-secret environment variables | No direct Encore primitive; use application constants for values that do not vary by environment or an external configuration service for runtime configuration |
| Logs, traces, and service information | Encore platform tracing, metrics, structured logging, and the service catalog |
| Hosted authentication, generated APIs, realtime features, and add-ons | Application code, another service, or an external dependency |
These primitives are declared in application code using TypeScript or Go.
Platform-specific features may need to be reimplemented, replaced, or kept as external services.
Choose where the application runs
Encore supports three deployment models:
- Encore Cloud Hosting: Encore runs the application containers and supporting infrastructure on Encore-managed infrastructure. It does not require your own cloud account and is intended for development and preview environments, subject to usage limits.
- Your AWS or GCP account: The Encore platform deploys the application and provisions supported resources in an account you own, using the environment's infrastructure configuration.
- Self-hosted: You deploy the image produced by
encore build docker, provision the physical infrastructure, and connect the declarations to it using an infra config file.
Cloud development and preview environments use the Encore platform Hosting by default. Hosting preview environments in your own cloud is available on the Enterprise tier. Self-hosted deployments configure their own metrics and logging destinations through the infra config and deployment environment.
Migrate data and platform services
Postgres databases
Encore databases use Postgres and apply schema changes from migration files. For an existing database, choose between importing the current instance and transferring the data to a new instance.
The Encore platform can connect directly to supported existing AWS RDS, Google Cloud SQL, and Neon databases. When importing RDS or Cloud SQL with a schema not previously managed by Encore, follow the bootstrap migration procedure in the relevant import guide. Existing Neon databases may require role ownership changes before Encore can run migrations.
Import a supported database when it should remain in place. Transfer the schema and data when the provider is unsupported or when the Encore platform should provision the target. For self-hosted deployments, the infra config can map the application declaration to an existing Postgres database.
When transferring a database, plan version compatibility, extensions, roles, connection cutover, and any required downtime.
Platform-specific services
Hosted authentication, generated data APIs, realtime subscriptions, edge or serverless functions, persistent volumes, and marketplace add-ons do not always have direct Encore equivalents. For each feature, choose whether to:
- implement it in an Encore service
- replace it with an Encore primitive or another provider
- continue using it as an external dependency
Migrate these features independently; they do not all need to move at once.
An external dependency remains outside Encore's provisioning lifecycle. Application code uses the provider's normal client or SDK, sensitive credentials are stored as Encore secrets, and the existing platform or infrastructure tooling continues to manage the service.
Deployments and preview environments
After connecting a GitHub repository, pushes to configured branches can trigger deployments. The Encore platform Pro can also create an ephemeral preview environment for each pull request. See Deploying applications for the available deployment methods.
Infrastructure running in your AWS or GCP account is billed by the cloud provider. The Encore platform usage depends on the features and pricing of your Encore plan.
Plan the migration
- Inventory application services, data stores, scheduled work, add-ons, secrets, domains, and network dependencies.
- Map supported infrastructure to Encore primitives and identify platform services that need separate migration work.
- Create an Encore application and move one service at a time, or wrap the existing HTTP router in a catch-all handler. See Migrating an existing system to Encore for both approaches.
- Validate the application locally and in a development or preview environment.
- Import or migrate stateful resources and verify schema and data compatibility.
- Switch traffic using the existing custom domain or gateway after the new environment is ready.
- Keep the previous deployment available until the Encore environment has been verified.
The cutover strategy and downtime requirements depend on the application and its data migration.
Platform-specific guides
- Supabase: migrate Postgres data and plan replacements for Auth, Storage, Realtime, and Edge Functions.
- Firebase: migrate document data and plan replacements for Authentication, Security Rules, Storage, and Functions.
- Railway: map services, variables, databases, volumes, and cron jobs.
- Heroku: map dynos, process types, config vars, add-ons, and Review Apps.
- Vercel: move backend functions while keeping a Vercel-hosted frontend when appropriate.
- Fly.io: map Machines, volumes, private networking, and managed services.
Next steps
- Follow the Quickstart guide to evaluate the local workflow.
- Then choose between the Encore platform deployment and self-hosting.