22
33This project uses AWS CDK (with TypeScript) to build CloudFormation templates for deployment of all resources for the
44SpyLogic application. The main stack defines a CodePipeline, configured with a single Stage to deploy the application
5- stacks on merging into the repo main branch.
5+ stacks on merging into the repo ` main ` branch.
66
77The API layer is a _ fairly_ typical containerized Node Express server, managed by AWS Fargate with a load-balancer in
88front. The UI is S3-hosted and served through CloudFront, and Cognito handles AuthN / AuthZ.
@@ -12,7 +12,8 @@ authorize users (via Cognito) when accessing the API. This seemingly simple task
1212Application Load Balancer (ALB), which only allows _ initiating_ authentication rather than verifying an existing access
1313token. The solution is to re-use our CloudFront distribution for the UI to proxy API requests as well, with an Edge
1414function to verify the token and, if verified, insert a custom header into the request before passing to the load
15- balancer. We then filter requests at the load balancer, and reject any requests without the expected header / value.
15+ balancer. We then filter requests at the load balancer, and reject any requests without the expected header and value,
16+ to prevent attempts to bypass auth.
1617
1718This should be much easier, as it is natively supported by API Gateway, but it seems ALB is yet to catch up.
1819
@@ -44,22 +45,58 @@ need to be deleted manually in the AWS Console.
4445As the pipeline deploys the application stacks, it is wise to test any changes to those stacks before committing them.
4546You can do this by synthesizing just the application stacks locally, and deploying to AWS as ` dev ` stage.
4647
47- There is one small task to complete before you begin. In AWS Secrets Manager, you will find a secret storing API key and
48- secret values for the ` prod ` stage, which the server needs for successful startup. You must create a new secret for the
49- dev stage, with the same OPENAI_API_KEY value and any random string for SESSION_SECRET. Once that is in place, you can
50- synthesize and deploy the stacks for testing. Once you have finished, please delete the secret to avoid unnecessary
51- costs.
48+ Before you begin, ensure you have added [ your API key] ( #server-secrets ) into AWS Secrets Manager, for the dev stage.
49+ Once you have finished testing, we recommend deleting the secret to avoid unnecessary costs.
5250
53- ` npm run cdk:test:synth ` - synthesizes just the application stacks (i.e. not the pipeline)
51+ ``` shell
52+ # synthesize the application stacks (no pipeline)
53+ npm run cdk:test:synth
54+
55+ # deploy resources to AWS as "dev" stage
56+ npm run cdk:test:deploy
57+ ```
58+
59+ Once this is complete, you will need to set some environment vars for the UI build. Copy the following stack outputs
60+ from the above deployment command into file ` frontend/.env ` , using [ .env.example] ( ../frontend/.env.example ) as a
61+ template:
5462
55- ` npm run cdk:test:deploy ` - deploys these stacks to AWS as "dev" stage
63+ - from dev-spylogic-auth-stack,
64+ copy UserPoolId, UserPoolClient and UserPoolDomain into corresponding properties
65+ - from dev-spylogic-hostedzone-stack,
66+ copy ` HostUrl ` into VITE_COGNITO_REDIRECT_URL, and ` BackendUrl ` into VITE_BACKEND_URL
67+
68+ Also uncomment VITE_AUTH_PROVIDER. Once that is done, run the following commands:
69+
70+ ``` shell
71+ # Build the UI
72+ cd ../frontend
73+ npm run build
5674
57- All being successful, you should see the application login screen at ` https://dev.spylogic.ai ` . Log into the AWS Console
58- to add a user to the dev Cognito userpool, then log into the UI to test app deployment was successful.
75+ # Deploy to S3
76+ aws s3 sync dist s3://dev-spylogic-host-bucket
77+ ```
78+
79+ All being successful, you should see the login screen when you navigate to the ` HostUrl ` (see above).
80+ Before you can sign in, you'll need to add a user to the dev userpool in Cognito, in AWS Console. After that, log into
81+ the application UI and check everything works as expected - including authenticated calls to the API, and session
82+ persistence via the SpyLogic.sid secure cookie.
83+
84+ Finally, remember to destroy the stacks after testing, else you will rack up costs:
85+
86+ ``` shell
87+ # Tear down all deployed resources
88+ npm run cdk:test:destroy
89+ ```
5990
60- ` npm run cdk:test:destroy ` - Remember to destroy the stacks after testing, else you will rack up costs!
91+ ## Troubleshooting
6192
62- ---
93+ - ` SSOTokenProviderFailure: SSO Token refresh failed. Please log in using "aws sso login" ` - Go on, try it!
94+ - Deployment of the spylogic-api-stack fails with "docker authorization token expired" error. Try this:
95+ [ docker login for AWS] ( https://stackoverflow.com/a/66919813 )
96+ - AccessDenied page when accessing UI. If deploying manually for testing the stacks, did you forget to deploy the UI to
97+ the host bucket? If deployed via the pipeline, check CodePipeline in AWS Console to see if the task failed.
98+ - UI seems stuck on old version even after merging to main. Is the pipeline awaiting manual approval? This can happen
99+ if changes made to a stack broaden any required permissions.
63100
64101## A note on costs
65102
0 commit comments