AWS CDK stack in TypeScript for the deployment of purplship-server.
Purplship is an open-source multi-carrier shipping platform. It's an exciting project that's supported by a growing community of businesses and developers.
After cloning this repo and completing the Get Started steps below, you can deploy this stack to your AWS account by executing the command: cdk deploy.
The deploy output includes the URL of the Application Load Balancer that you can use to access the admin interface. The Get Started section details how to access the admin password that was generated by AWS Secrets Manager.
This stack's default configuration runs purplship-server in DEBUG_MODE and emphasizes a quick start over security. Please take proper precautions before inputting any confidential information such as live carrier credentials into the purplship-server admin interface.
Running this stack on a live AWS account will incur usage charges with Amazon/AWS.
You can remove the resourecs created by this stack from your AWS account via cdk destroy. You can also delete this stack manually from within the AWS Console by finding it in the AWS CloudFormation dashboard and deleting it from there.
Ensure that you have an active AWS account with current billing details.
Ensure that you have a valid AWS configuration in ~/.aws/config and have specified valid API credentials in ~/aws/credentials.
A global installation of the aws-cdk package is recommended: yarn global add aws-cdk.
Run cdk --version to confirm your installation.
If this is your first time using this stack, install the project's dependencies by running: yarn.
If this is your first time using AWS CDK with your particular AWS account, run cdk bootstrap from the root of the project folder.
This will create the AWS resources that AWS-CDK requires to run. The resulting stack will appear in CloudFormation with the name "CDKToolkit".
AWS CDK is frequently updated. It is highly recommended that you run the latest version of all packages related to the CDK.
To check for and install any available updates you can use yarn's upgrade-interactive feature:
# review potential updates for globally installed packages
yarn global upgrade-interactive --latest
# review potential updates for packages in this project
yarn upgrade-interactive --latestIt is important that the globally installed version of aws-cdk has the same version number as the @aws-cdk-related dependencies listed in package.json.
Run cdk --version to confirm your cli version. You can check the version number against the versions of the dependencies listed in package.json.
Open bin/purplship.ts to find the ADMIN_EMAIL prop and replace the value with your preferred admin email address.
If you do not specify an ADMIN_EMAIL, this stack will default to admin@example.com.
This stack will generate an admin password via Secrets Manager. See the Access... instructions below for details on how to access it.
Refer to the stack implementation in stacks/purplship-stack.ts to understand other supported props that can be passed to the PurplshipStack constructor.
Run cdk synth to generate a CloudFormation stack and confirm that there are no errors.
Run cdk deploy to deploy the stack to your AWS account.
Note that AWS can sometimes take a while to fully configure and deploy a new stack.
After deploying the stack via cdk deploy:
Review the console output from executing cdk deploy and look for the line of output that starts with PurplshipStack.LoadBalancedFargateServiceURL.
Access the purplship-server Admin UI by navigating to the URL in your web browser.
To login, use the admin email that you specified earlier as the ADMIN_EMAIL. If you did not replace the default with your own email, this stack will have used admin@example.com.
Query Secrets Manager via the aws cli to obtain the admin password that was generated:
# if you do not have the `jq` utility installed (outputs a raw json string may include backslash escape characters):
aws secretsmanager get-secret-value --secret-id purplship/admin --query SecretString
# if you do have the `jq` utility installed (outputs only the admin password):
aws secretsmanager get-secret-value --secret-id purplship/admin --query SecretString --output text | jq -r '"\(.password)"'You can also view the generated credentials via the Secrets Manager dashboard in the AWS Console. Open the secret named purplship/admin and click the Retrieve Secret Value button.
After this stack has deployed, you can view the resources that it created in the AWS Console:
- CloudWatch: check the aws/ecs/purplship-server logs group to view application log output (you can also add alerts)
- Secrets Manager: find the purplship prefixed secret names (for app, db, and admin secrets) in Secrets Manager
- CloudFormation: the PurplshipStack is listed in the dashboard (you can delete + troubleshoot stack deploys/updates)
- Elastic Container Service: find the cluster and task definitions corresponding to this stack
- EC2: the Load Balancers section of the dashboard lists the Application Load Balancer
- Systems Manager: the Parameter Store section lists the ARN's of the secrets (useful for enabling other resources to access secrets values)
If you fork this repo to customize it for your own needs, you may want to consider removing cdk.context.json from the .gitignore file and committing this file to your repo. Refer to the AWS CDK documentation for more details about the CDK Context.
The configuration details that instruct CDK Toolkit how to execute this solution can be found in the cdk.json file.
This stack is not a production-ready configuration. It may be helpful as a starter or reference to help you save time writing a stack that's suited to your particular business needs and production requirements.
You may wish to consider incorporating the following into a production stack for purplship-server: TLS/SSL throughout, higher-spec resources, RDS clusters vs. instances, robust backups and recovery, detailed logging and monitoring, adding protections to prevent accidental deletion of resources, adding secret and key rotation, using KMS, etc., etc.
This stack does contain a few production-worthy tidbits for inspiration. For example: using Secrets Manager to generate and store all credentials and secrets.
If you need professional help configuring purplship or integrating it into your business, please consider supporting the project by using purplship's professional + enterprise service offerings.
You can also email the author of this stack at hello@firxworx.com to inquire if I am available for hire in a consulting capacity. Please note that I work for a shipping and logistics firm in Ontario, Canada, so I may not be able to provide services to a potential competitor!
cdk synthemits the synthesized CloudFormation templatecdk diffcompare deployed stack with current statecdk deploydeploy this stack to your default AWS account/region