Introduction

This guide describes how to migrate your application running on Heroku to AWS using Stacktape. It covers all required steps you need to take to deploy your application and database on AWS.

1. Install Stacktape and connect your AWS account

1. If you do not have Stacktape account yet, you can sign up here.

2. After signing up, connect your AWS account in Stacktape console

3. After connecting account, install Stacktape CLI using single command

   Windows (PowerShell)

   Linux

   Macos

   Macos ARM

   Copy

   iwr https://installs.stacktape.com/windows.ps1 -useb | iex

4. (OPTIONAL) If you are using VS code we recommend to install VS code extension

Entire install process is described in greater detail in our Install Stacktape docs

2. Define your resources

You can define your resources by creating a config(a blueprint) of your environment. The config contains all the information needed for Stacktape to deploy your application.

1. Create config file stacktape.yml in your application's project directory.

2. Add web-service resource to your config

   Since you are coming from Heroku, you will probably want to use Web Service resource for your application. Web service is a simple container-based resource that runs your code with public URL and port exposed for HTTPS communication(automatic SSL out of the box) similar to Heroku's web dyno.

   Alternatively you can use private-service or worker-service(similar to Heroku's worker dyno).

Copy
serviceName: my-service # choose arbitrary service name

resources:
  appService:
    type: web-service
    properties:
      packaging:
        type: external-buildpack
        properties:
          sourceDirectoryPath: ./
          builder: heroku/builder-classic:22
      resources:
        cpu: 1
        memory: 1024
      cors:
        enabled: true

Your web service definition contains everything Stacktape needs to know including how to build and package your app. In our example, we are using heroku's buildpacks builder(same way heroku builds and packages apps) which automatically detects the language and the framework of your application.

However, you can also choose to package app by:

• providing a Dockerfile
• using our built-in, zero-config Stacktape Image Buildpack.

To see all packaging options refer to Web Service packaging docs.

3. Add database

Adding database is as simple as adding it to your stacktape.yml config.

1. We are adding relational database resource to the template (you can choose any engine type and version according to your needs)

2. We are referencing database resource in connectTo list of our web service. This will inject environment variables containing information required for connecting to the database (such as STP_DATABASE_CONNECTION_STRING) into the web service.

   You might need to modify your code to use these variables. Refer to database docs and web service docs for more details on how it works.

Copy
serviceName: my-service # choose arbitrary service name

resources:
  appService:
    type: web-service
    properties:
      packaging:
        type: external-buildpack
        properties:
          sourceDirectoryPath: ./
          builder: heroku/builder-classic:22
      resources:
        cpu: 1
        memory: 1024
      cors:
        enabled: true
      connectTo:
        - database

  database:
    type: relational-database
    properties:
      credentials:
        masterUserName: king
        masterUserPassword: my-supper-password
      engine:
        type: postgres
        properties:
          primaryInstance:
            instanceSize: db.t3.micro

4. Deploy your app

You can deploy your application by running single command in your project's directory.

We recommend to use stacktape codebuild:deploy command (<<stage>> is arbitrary string, i.e dev-thomas or test or prod):

Copy
stacktape codebuild:deploy --stage <<stage>>

Stacktape codebuild:deploy command:

• zips your project,
• uploads it to S3 bucket in your AWS account
• deploys your app remotely using managed AWS CodeBuild server within your account.

Alternatively to using codebuild:deploy command, you might use stacktape deploy command, which will perform deployment from your local workstation. In this case you will need dependencies(such as Docker) installed on your workstation.

5. Explore your app

After successfully deploying your application, Stacktape will print URL of your application to the terminal.

Additionally it will also print link to the Stacktape console where you can view information about your application stack (including where to find logs, monitoring metrics etc).

FAQ

How to configure custom domain?

Refer to the docs on how to configure custom domain.

How does auto scaling work?

Web Service auto scale based on CPU/Memory usage thresholds. For more info, refer to the web service docs on auto scaling.

Can I monitor health of my app?

Yes. Health is actually monitored out of the box. If your web service task(container) is deemed unhealthy(i.e your app crashes due to some bug), the task is automatically replaced with healthy one.

Moreover, you can easily set up your own internal health-checks. If a task fails this health-check, it is deemed unhealthy and replaced.

Is my app available during updates?

Yes. When you decide to deploy new version of your app(update to a new version), Stacktape uses rolling update strategy. This means that any old web service task(container) is only removed when a new healthy task replaced it.

Besides rolling update strategy, you can also choose from multiple types of BLUE/GREEN deployment strategies.

Can I use CDN in front of my app?

Yes. Many applications can benefit from CDN. CDN can offload your services by caching responses, which results in less requests coming to the app which leads to less compute power consumed and paid for. With Stacktape you can enable CDN with single line of config

Can I manage Atlas MongoDB clusters using Stacktape?

Yes. You can seamlessly manage Atlas MongoDB clusters using Stacktape.

Do you support other resources?

Yes. We support many resource types(container based, lambdas, batch jobs...) fitting all of your needs. See our docs.

Is Stacktape extensible?

Yes. Except for plethora of AWS and 3rd party resource types Stacktape integrates by default, you can also extend your infrastructure using AWS CDK or AWS Cloudformation.