Documentation: Flowy on AWS using EC2

Please support us to improve our service. We would like to use statistics anonymously.

We do not pass on your data! You can find more information in our privacy policy.

Decline

< Back to documentation

When working with Flowy on AWS, there are two different scenarios to distinguish:

  1. Hosting Flowy itself: setting up the Flowy platform (admin and processing services) on your own AWS infrastructure, so that applications can be built and operated on it.
  2. Deploying an application powered by Flowy: making an application that was built with Flowy available to its end users.

The following sections describe the required AWS setup for each scenario.

Hosting Flowy itself

Assumptions

The following guide assumes that separate Load Balancers shall be set-up for the admin respective processing services and that CloudFront is used (at least) to serve the Flowy admin portals content.

Preparation

  1. Consider a host naming convention. A suggestion:
    • admin.example.com for the admin front-end, to be used by the users, will point to CloudFront
    • admin.lb.example.com will be used for the admin load balancer
    • processing.lb.example.com will be used for the processing load balancer
  2. Look up and write down the IP address range configured for the VPC

Execution

  1. Set up a S3 bucket, enable static website hosting and upload Flowy front-end. Please ensure that the index.html is displayed within the root folder of the bucket.
  2. Set up the ec2 instance(s) and install the admin respective processing services. The services can run on the same or different ec2 instances. Make sure to write down the ports being used, by default 8080 for admin and 8081 for processing.
  3. Create and assign security groups to the ec2 instance(s). It is highly recommended to limit access to these internal port by defining the VPC CIDR (=the VPC's internal IP range) as only allowed IP. Alternatively, it is also possible to limit the access to the Load Balancers IP, see the according AWS documentation What's the source IP address of the traffic that Elastic Load Balancing sends to my web servers?open in new window .
  4. Set up public certificates in N. Virginia (!) and complete the validation; this certificate will be used for CloudFront.
  5. Set up a CloudFront distribution, configure the domain name and the newly generated certificate. Add the s3 bucket as default source and make sure to set "Redirect HTTP to HTTPS" as viewer protocol policy.
  6. Set up public certificates to be used for the load balancers, these must be created in the same region as the EC2 and load balancers.
  7. Configure load balancer in front of both services and consider the two different health check URLs:
    • admin: /api/actuator/health
    • processing: /actuator/health (depending on the usage of CloudFront)
  8. Create DNS entries for both services and point them to the load balancers.
  9. Open the previously generated CloudFront distribution and create a new source pointing to the admin DNS entry and using /api as path pattern. Make sure to set "Redirect HTTP to HTTPS" as viewer protocol policy, allow all HTTP methods (GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE) and configure CachingDisabled as cache policy respective AllViewer as origin request policy.
  10. Add a second source pointing to the processing service and use /rest as path pattern. Use the same settings as for the admin service.
  11. Create DNS entry for admin (and optionally for processing) and point it to the CloudFront.
  12. Done: your newly configured environment is ready to be used!

The above guide intends to provide overview of the necessary actions. Please check and follow the AWS guides and experts to ensure that your environment is hardened and safe for public usage.

HINT

Consider setting the <flowyContextPath> in order to support prefixes like i.e. /api. See Flowy Configuration for details.

Deploying an application powered by Flowy

Assumptions

The following guide assumes that the domain example.com is using Route 53 for its DNS management - the domain must use a Route 53 public hosted zone as its authoritative DNS zone - and that the Flowy processing service is already available behind a load balancer (see the previous section). The application can be made available either under a sub-domain like host.example.com or directly on the root domain example.com - simply use the according domain name in the steps below.

Execution

  1. Create a S3 bucket for the application front-end.
  2. Grant CloudFront access to the bucket contents. These are two different models - pick one, do not mix them:
    • Recommended - private bucket with Origin Access Control (OAC): keep Block Public Access enabled and do not enable static website hosting. CloudFront connects to the normal S3 REST endpoint; when adding the S3 origin to the CloudFront distribution (see below), create and attach an Origin Access Control and apply the generated statement to the bucket policy, so that only the distribution is allowed to read the bucket contents.
    • Alternative - S3 static website endpoint: enable static website hosting on the bucket, setting both the index document and the error document to index.html. The error document ensures that requests for unknown paths still return the application (though with HTTP status 404). This model requires public read access and CloudFront connects to the S3 website endpoint over HTTP only.
  3. Upload the application content to the bucket. This can be done either through Flowy (using the upload feature of the application object) or manually. After each deployment, invalidate at least /index.html in CloudFront, or /* if filenames are not content-hashed.
  4. Create a CloudFront distribution:
    • Add two origins: the processing service's load balancer (make sure to use the processing load balancer URL, like your-alb.region.elb.amazonaws.com) as well as the S3 bucket.
    • Add a behaviour with the path pattern api/* pointing to the load balancer origin, using these settings:
      • Compress objects automatically: No
      • Viewer protocol policy: Redirect HTTP to HTTPS
      • Allowed HTTP methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
      • Restrict viewer access: No
      • Cache policy: create and select a custom cache policy that disables caching completely (equivalent to the managed CachingDisabled policy), like myapp-caching-disabled
      • Origin request policy: create and select a custom origin request policy that forwards all viewer headers, cookies and query strings to the origin (equivalent to the managed AllViewer policy), like myapp-api
    • Set the default behaviour to point to the S3 origin, using these settings:
      • Viewer protocol policy: Redirect HTTP to HTTPS
    • Set the default root object to index.html.
  5. Create an IAM user with an access key pair to be used for deployments. Grant a least-privilege policy covering both managing the bucket contents and refreshing the CDN:
    • s3:ListBucket on arn:aws:s3:::bucket-name
    • s3:GetObject, s3:PutObject, s3:DeleteObject on arn:aws:s3:::bucket-name/* (s3:GetObject is needed by many deploy/sync tools for comparisons or metadata checks)
    • cloudfront:CreateInvalidation on the distribution ARN
  6. Generate the SSL/TLS certificate in AWS Certificate Manager:
    • Open AWS Certificate Manager / ACM.
    • Switch the AWS region to US East (N. Virginia) / us-east-1. This is required for CloudFront!
    • Choose "Request certificate".
    • Choose "Request a public certificate".
    • Add the domain name the certificate should cover: host.example.com respective example.com. Optionally, also add www.example.com (needs to be put in the same certificate as example.com). Note that a wildcard certificate for *.example.com covers host.example.com, but it does not cover the root domain example.com - for root-domain production, include example.com explicitly.
    • Choose DNS validation.
    • Submit the request.
    • Open the pending certificate and choose "Create records in Route 53".
    • Confirm the hosted zone and create the validation records.
    • Wait until the certificate status becomes "Issued". Usually this takes <= 5 min.
  7. In CloudFront, open your distribution and add the domain under "Alternate domain names / CNAMEs": host.example.com respective example.com (and optionally www.example.com).
  8. Attach the matching ACM certificate to the CloudFront distribution. Important: for CloudFront, the ACM certificate must be in us-east-1 / N. Virginia.
  9. Wait until the CloudFront distribution status is "Deployed".
  10. Open the hosted zone in Route 53.
  11. Choose "Create record" and set:
    • Record name: host for the sub-domain; for the root domain, leave it empty or set it to example.com, depending on the Route 53 UI
    • Record type: A
    • Alias: enabled
    • Route traffic to: Alias to CloudFront distribution
    • Distribution: select your CloudFront domain, like dxxxxx.cloudfront.net
    • Evaluate target health: No
  12. Create the record.
  13. If you use the optional www.example.com domain, create an additional alias record with the record name www, using the same settings otherwise. Adding www.example.com to the certificate and the CloudFront alternate domain names is not enough - it needs its own Route 53 alias record.
  14. Wait for ~ 10 minutes. Even with a short TTL configured for your domain, DNS propagation and the CloudFront deployment can still take a few minutes.
  15. Check the setup:
    • On Windows using PowerShell:
      nslookup host.example.com
curl.exe -I https://host.example.com
    • On other operating systems:
      nslookup host.example.com
curl -I https://host.example.com
  16. Done: your application is now available under its own domain!