Deploying to AWS

There are two different sub-generators for deploying JHipster projects to AWS:

• aws-containers: A Docker container based sub-generator for deploying applications via AWS Elastic Container Service. This is great for complex applications and/or microservice architectures.
• aws: An instance based sub-generator for deploying applications via Elastic Beanstalk. This is great (and very cheap!) for simple applications.

aws-containers sub-generator

This sub-generator will automatically deploy your docker-based JHipster application, using AWS Fargate running on Elastic Container Service. It leverages a number of AWS services to achieve this:

• AWS Fargate: A new AWS service which allows containers to be run without needing to worry about the underlying VM instance infrastructure. The sub-generator currently uses Elastic Container Service to manage the containers.
• Elastic Container Registry: A Docker Image repository, where the application images are stored.
• Elastic Load Balanacer - Network Load Balancer: The Network Load balanacer is used to direct traffic to containers.
• Aurora: A AWS managed database service, which is MySQL and PostgreSQL compatible.
• AWS S3: File storage used to store CloudFormation scripts.
• CloudWatch: Distributed log collection tool used to view the status of containers.
• AWS Cloudformation: All required services (besides AWS System Manager Parameters) are defined in a set of CloudFormation files. The base file contains high level services, and then each application is defined in its own file, which is called a nested stack.
• AWS System Manager - Parameter Store: A Secure password storage mechanism, which is used to store the database password. Running the sub-generator will introduce a new Spring Cloud component which will read in the password on application startup.
• AWS - IAM Role: The generator creates a new role which the ECS tasks will execute under, with an associated policy.

If you choose to deploy the application, the sub-generator will go through a number of steps before the application starts.

1. Rebuilds the application’s Docker Imager, so it includes the newly generated Spring Cloud classes.
2. Creates an S3 bucket for the CloudFormation YAML files.
3. Uploads the Cloudformation YAML files to the S3 bucket.
4. Creates the CloudFormation stack (excluding the ECS Service). The service is initially excluded so we have the opportunity to upload the required Docker Images into the newly created registry so the service will start successfully when its created.
5. Tag Docker Images and Upload to Registry.
6. Set Database access password in AWS SSM. This has been excluded from the Cloudformation file because it currently does not support SecureStrings, and it is bad-practice to store passwords within Cloudformation.
7. Update Stack to include ECS Service. Prints out Load Balancer URL.

Limitations

• Currently only works with monolithic applications.
• Only the following database types are supported (all via Aurora): Mysql, MariaDB and PostgreSQL.
• Fargate is, at time of writing, only available in the us-west-2 region. Check this list before attempting to run the sub-generator against a different region.
• Instance to instance communication is currently not supported. The biggest consequence of this is that cache synchronisation is not supported between nodes. It is recommended to look at AWS’ ElasticCache service for distributed caching requirements.
• SSL is not enabled.

Costs

The services used by this generator are not covered by the AWS Free Tier. This generator is designed to allow applications to be run in a production-grade manner, and at this time is not recommended for small or cost sensitive workloads.

Running the sub-generator

Before running the sub-generator, you need to setup your AWS credentials so they are accessible. Although you do not need the Amazon CLI installed for this generator to work, it’s recommended for subsequent development purposes. Log in with your Amazon AWS account and create a user for your JHipster application. After that create a credentials file at ~/.aws/credentials on Mac/Linux or C:\Users\USERNAME.aws\credentials` on Windows. An alternative to the credentials files is to use environment variables to set your Access Key ID + Secret.

Within a new folder run:

jhipster aws-containers

The sub-generator will ask a number of questions regarding how you would like your application deployed, using information it will determine from your AWS environment. There are a couple of things to consider:

• The application can be deployed in either a single tier (using a default VPC configuration), or a two-tier model (example CloudFormation file here). When determining your deployment subnets, you should ensure that the application is being deployed across at least two Availability Zones, otherwise Amazon Aurora will not deploy correctly.
• If you need to remove the generated CloudFormation stack, you must remove all created ECR images before attempting to delete the stack. CloudFormation cannot delete the registry if it is still holding images.

Updating your deployed application

When your application is already deployed, you can re-deploy it by run the sub-generator again:

jhipster aws-containers

You will be re-prompted to confirm your settings, giving you the oppoortunity to re-adjust things like the performance level. Note, in some circumstances the application will have issues terminating the previously deployed task instances, which may require them to be manually terminated via the console or CLI.

Deleting your application

To delete your deployed application:

• Navigate to Elastic Container Service > Repositories > [Your application names] and delete all images within the repository. Do not delete the repository itself. You cannot delete the application via CloudFormation if there are images within the repository.
• Navigate to CloudFormation and delete the stack which you have created. This will deprovision the majority of services.

For a complete cleanup of your environment, there are two additional configurations which need to be deleted.

• Remove the stored password via AWS Systems Manager > Parameter Store.
• Remove the CloudFormation template files from the generated S3 bucket, which is in the format [Stack Name]-[timestamp].

aws sub-generator

This sub-generator allows to deploy automatically your JHipster application to the Amazon AWS cloud using Elastic Beanstalk.

Limitations

• You can only use it with a MySQL database (PostgreSQL and Oracle will be added later).
• Websockets doesn’t work behind the load balancer by default.

Running the sub-generator

Before running the sub-generator, you need to setup your AWS SDK credentials. Log in with your Amazon AWS account and create a user for your JHipster application. To grant this user the required permissions attach the AWSElasticBeanstalkFullAccess policy.

After that create a credentials file at ~/.aws/credentials on Mac/Linux or C:\Users\USERNAME\.aws\credentials on Windows.

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

To deploy your application to Amazon AWS, type:

jhipster aws

This should package your application in “production” mode, create an Bean Stalk application (with a MySQL database), upload your code, and start the application.

Updating your deployed application

When your application is already deployed, you can re-deploy it by run the sub-generator again:

jhipster aws

The sub generator ask your database credentials again but they will be ignored during the update.

More information

• AWS SDK for JavaScript
• Progressbar for WAR upload