apppackCLI (see install)
- An AWS account with Credentials for an admin user or role.
- 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.comor 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.
- 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.
- [Optional] Add our GitHub Application to your repo or organization to integrate deployment information.
Setting up AWS
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:
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.
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.
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.
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:
apppack create account
apppack create region
apppack create cluster
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.
Don't start creating apps until you've received confirmation that your account is ready.
No resources in the account stack should incur AWS charges.
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.
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
- 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.comas your domain, an app named
my-appwill be accessible at
my-app.cluster.example.comin 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>
The database stack will create resources which incur AWS charges. These include:
- RDS Instance(s). Control the instance class used with 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>
The Redis stack will create resources which incur AWS charges. These include:
- Elasticache Node(s). Control the instance class used with 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.
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