Skip to content

Initial Setup

Prerequisites

  1. The apppack CLI (see install)
  2. An AWS account with Credentials for an admin user or role.
  3. A Route53 Hosted Zone setup in your AWS account for a domain you'll use to route traffic to your applications. This can either be a top-level domain like example.com or a subdomain like apppack.example.com. If you wish to use a subdomain and the top-level domain is hosted elsewhere, see these instructions. If your using a registrar other than Route53, make sure your nameservers are setup for the Hosted Zone there.
  4. A free Docker Hub account and access token (generated at https://hub.docker.com/settings/security). This is required to avoid the anonymous IP rate limits for pulling base images.
  5. [Optional] Add our GitHub Application to your repo or organization to integrate deployment information.

Setting up AWS

All commands in the setup process require AWS credentials, either via environment variables or a credentials file.

Tip

Be sure to specify the AWS region you want to deploy to. You can do this via --region flag or by using the AWS_REGION environment variable. For example, AWS_REGION=us-east-1 apppack create ... or apppack create --region us-east-1 .... AppPack currently supports the following AWS regions: us-east-1, us-east-2, us-west-1, us-west-2.

Once an administrator sets up these initial resources, direct AWS credentials are no longer necessary to manage applications. AppPack handles user authentication while maintaining the use of AWS Identity Access Management (IAM) for authorization.

The create and init commands below all accept a --check flag which will allow you to audit the resources that will be created prior to making any changes in your AWS account.

Pricing

You will incur AWS charges for some resources used by AppPack. We'll make a note of what to expect where applicable.

Some resources are such as EventBridge Events, SSM Parameters, and Lambda Functions are priced so low (fractions of a cent/month) or have such generous free tiers that they are not included in the notes.

To track the cost of your AppPack resources, we recommend setting up User-Defined Cost Allocation Tags. All AppPack resources will get an apppack:* tag you can use for fine-grained tracking.

Also don't forget about the Free Tier, Reserved Instances, Savings Plans and AWS Activate Startup Credits!

apppack init

apppack init is the first thing you should run. It will create all the resources at AWS necessary to start deploying apps. The init command steps your through each of the following:

  1. apppack create account
  2. apppack create region
  3. apppack create cluster

Account Creation

Account creation will set up the global resources for AppPack authentication and authorization. Once complete it will output role information necessary for us to setup your AppPack account.

Warning

Don't start creating apps until you've received confirmation that your account is ready.

Account Pricing

No resources in the account stack should incur AWS charges.

Region Creation

Region creation sets up some resources that are specific to the AWS region you're deploying to. You'll be prompted for the Docker Hub credentials noted in the Prerequisites above.

Region Pricing

No resources in the account stack should incur AWS charges.

App Cluster Creation

Every app is deployed to a cluster. A cluster may contain multiple apps. The cluster consists of a load balancer, security groups, compute resources, etc. You'll be prompted for:

  • The name to identify your cluster. The default is apppack.
  • The domain to route to your cluster. This should be the same domain, or a subdomain of the domain you created a Hosted Zone for in the Prerequisites. This domain serves as the parent domain for all apps in the cluster. If you use cluster.example.com as your domain, an app named my-app will be accessible at my-app.cluster.example.com in addition to any custom domains you se tup for the app.
  • The EC2 instance class that will make up the autoscaling group for your cluster.

App Cluster Pricing

The cluster stack will create resources which incur AWS charges. These include:

Creating a Database Cluster (Optional)

If your applications require a supported RDMS (MySQL or Postgres), you can add a managed RDS database to your cluster. Database stacks are designed to be shared across multiple apps in a cluster, but a cluster may have multiple database stacks. If you wish to isolate a single app to a single database, you can do that too.

apppack create database <name>

Database Pricing

The database stack will create resources which incur AWS charges. These include:

  • RDS Instance(s). Control the instance class used with the --instance-class flag.

Note: The --multi-az flag will create two database instances, doubling the cost of the database stack. This is recommended for production instances for maximum uptime, but not necessary for development apps or places where cost optimization is more important than uptime.

Creating a Redis Cluster (Optional)

If your applications require Redis, you can add managed Redis (via Elasticache) to your cluster. Redis stacks are designed to be shared across multiple apps in a cluster, but a cluster may have multiple Redis stacks. If you wish to isolate a single app to a single Redis stack, you can do that too.

apppack create redis <name>

Redis Pricing

The Redis stack will create resources which incur AWS charges. These include:

Note: The --multi-az flag will create two Redis instances, doubling the cost of the Redis stack. This is recommended for production instances for maximum uptime, but not necessary for development apps or places where cost optimization is more important than uptime.

Creating your first App

AppPack apps are largely compatible with apps built for the Heroku platform. Leveraging a Procfile to define services and app.json1 to define buildpacks, test scripts, etc. See apppackio/apppack-demo-python for a simple example.

Once your app is ready, run:

apppack create app <name>

If this is your first app, you'll be prompted to authorize Codebuild to pull from your repository and trigger new builds.

On completion, either push a new commit to the specified trigger branch or run apppack -a <your-app> build start --wait to trigger a build and wait for the deployment to complete. Note, the first deployment of the first app to a cluster takes a minute or two longer while the first EC2 instance is created.

App Pricing

The app stack will create resources which incur AWS charges. These include:

  • Any EC2 Instances necessary to increase the cluster capacity the demands of the app
  • CodeBuild minutes used during the automated build/test process
  • Cloudwatch Logs for storing application and build logs
  • Elastic Container Registry costs to store app images
  • S3 usage pricing if the add-on is enabled
  • SQS usage pricing if the add-on is enabled
  • SES usage pricing if the add-on is enabled

  1. The buildpacks, stack and environments[test] portions of app.json are currently supported.