Polkukone

The application is built using the AWS Serverless Application Model (SAM) and is deployed using the AWS Cloud Development Kit (CDK).

Project was initially created using the cdk init polkukone --language typescript command.

Original README.md file is available for reference as README-CDK.md.

Packages

For package specific instructions, you can refer to the following README.md files:

• packages/server/README.md - @polkukone/server is the Node.js application that provides the backend API for the PolkukoneStack.
  • AWS Secrets Manager is used to store the database credentials.
  • AWS RDS is used to host the MariaDB database instance.
    • Security group is configured within VPC to only allow access from the AWS Lambda functions.
  • Lambda's are used to run the application and it's database migrations and seeds.
  • AWS API Gateway is used to serve the Express.js API.
• packages/client/README.md - @polkukone/client is the Vue.js application that provides the frontend UI for the PolkukoneStack.
  • AWS S3 is used to host the application.
  • AWS CloudFront is used to serve the application.
    • Cache invalidation is triggered automatically when the application is deployed.

These README.md files provide detailed description about the packages and their dependencies and how to run them locally.

Requirements

• XCode - xcode-select --install
• Homebrew - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
• Node.js - brew install node@18
• Visual Studio Code - brew install visual-studio-code
  • VS Code is recommended editor for the project.
  • Project ships with VS Code Workspace Settings located at .vscode/.

Prerequisites

You should already have Git installed on your machine to use AWS CodeCommit. You can verify the installation by running:

git --version

If Git is not installed, you can install it using Homebrew:

brew install git

AWS CLI

Install and configure the AWS CLI with your credentials:

brew install awscli
aws configure

You will be prompted for your Access Key ID, Secret Access Key, default region, and output format. Enter these accordingly.

AWS CodeCommit

OS X includes a system-level Git credential store that might interfere with the AWS CLI's credential helper when attempting to connect to AWS CodeCommit repositories.

Insert following lines into your ~/.gitconfig file and you're able to use the credential helper for AWS CodeCommit repositories and the osxkeychain helper for all other repositories:

[credential "https://git-codecommit.*.amazonaws.com"]
    helper = !aws codecommit credential-helper $@
    UseHttpPath = true
[credential "https://github.com"]
    helper = osxkeychain
[credential "https://gitlab.com"]
    helper = osxkeychain

Setup

If the infrastructure has already been setup up using AWS CDK, you can skip the Infrastructure section and proceed directly to the Deployment section.

Infrastructure has been setup if the repository was cloned using the CodeCommit URL. In that case, the remote is already set to the CodeCommit repository and the infrastructure is most likely already deployed.

After inital deployment, the resources and services are updated using AWS CodePipeline and AWS CodeBuild. The pipelines are triggered by pushing changes to the main branch of the AWS CodeCommit repository.

npm/yarn/pnpm workspaces are not used currently. This is because lock file (package-lock.json/yarn.lock/pnpm-lock.yaml) is needed for each service and currently there's no way to do that with workspaces properly (there's some hackish community implementations so we'll wait for official solution).

Only downside is that we need to run npm install in each package directory separately and we don't get the benefit of hoisting dependencies to the root node_modules directory.

Infrastructure

Run the following commands to deploy the infrastructure using AWS CDK.

Install AWS CDK:

npm install -g aws-cdk

Set up the AWS CDK Toolkit stack in your AWS account:

cdk bootstrap

Install dependencies:

npm install

Deploy the CDK stack:

cdk deploy

CfnOutput outputs resources and services that are deployed by the CDK stack. You're able to access these resources and services using the URL's printed in the output.

Git Remote

Make sure your Git remote is set to the CodeCommit repository. HTTP & SSH clone URL's are printed in the output (CfnOutput) of the cdk deploy command.

If you would want to use GitHub instead of CodeCommit, you would need to change the repository property of the CodeCommitSourceAction in lib/polkukone-pipeline-stack.ts to GitHubSourceAction and set origin remote to the GitHub repository URL.

For GitLab, you would need to set repository mirroring to the GitLab repository URL as there is no GitLab source action available in AWS CDK currently.

Run these commands from repository root:

# Remove the default remote
git remote remove origin

# Replace the URL with the one from the output of `cdk deploy`
git remote set-url origin https://git-codecommit.eu-central-1.amazonaws.com/v1/repos/polkukone

Deployment

Push changes to the main branch of the CodeCommit repository and the pipeline will automatically deploy the changes to the resources and services.

Known Issues

• Sequelize auto increment get's fucked up when importing from multiple CSV sources (final bulkCreate operation)