Troubleshooting AWS installation

[]

Indeed, we cannot provide an exhausting list of possible troubles and their solutions. Below is the summary of the most common pitfalls and how to deal with them.

Where to look for hints

The following resources contain logs or errors or other information about service failures and its possible causes.

• CloudWatch logs

• Balancer target group: health check

• Service configuration

• One useful diagnosis tool is ssh access to the Docker host EC2 instance.

  • Install curl

  • Check in the service which port is exposed at a Docker‘s container

  • Try accessing the check URL of one container directly using curl -vs http://localhost:32.../hcms/v1.0/entity

  • If this reques fails, the problem is in the HCMS configuration. If it succeeds, the problem may be somewhere between the balancer and the Docker host (probably the firewall).

Most common causes

• When the service has no containers, then it is not configured correctly.

• If the target group contains "healthy" targets, but they cannot be accessed from outside, then the problem may be in the ALB Listener rules.

• The most common problem is that the targets are registered, but fail health check.

  • One possible cause is that the HCMS fails to start due to the server communication error: check CloudWatch logs for any errors.

  • Another common cause is incorrect firewall configuration, which prevents ALB to connect to the Docker containers: check Security groups of the Docker hosts (EC2 instances) and the balancer.

Replacing or recreating resources

Any time you re-create or change any resource in AWS, make sure to propagate this changes to any ther resources that refer to it.

E.g.:

• If you changed the task definition, you need to enter the new revision number in the service based on the task definition.

• If you pushed a new image to the ECR, you need to replace the image URI in the task definition, which may create a new revision: see above.

• If you created a new balancer, you need to make a new entry in the Route 53.

Placing resources in different regions

As already mentioned in the very beginning, please make sure to create all resources in the same region. It will help you to navigate between them, but also spares you additional configuration and troubleshooting.

E.g.:

• The server preparation part will by default create a DataStore.xml configuration asset and specify the region of the HCMS container as the region of the S3 buckket which is not correct. You will need to edit the DataStore.xml or use command line to adjust the configuration by using the -region argument as explained in more detail here.