In the blog, I will introduce how to scaffolding a Vue based frontend project in AWS Amplify from scratch. The template project is setup using Vite, AWS Amplify infrastructure is provisioned using Terraform. Both Vue source code and Terraform infrastructure code are managed and versioned in GitHub repository. Besides, GitHub Actions workflows are created to provision and manage Cloud infrastructure. New commits to GitHub repository will trigger a new deployment in Amplify App accordingly. In the end, you should know:
- How to setup a Vue based frontend template project from scratch.
- How to define and manage AWS infrastructure using Terraform.
- How to provision and manage AWS infrastructure via GitHub Actions workflow.
- Prerequisites
- Preparation
- Scaffolding Vue Project
- Setup Terraform Infrastructure
- Provision Terraform Infrastructure using CLI
- Demo Project
- Next Step
- Summary
The Demo Repo: https://github.com/camillehe1992/amplify-vue-app
Prerequisites
- A GitHub account
- permission to create an empty repository
- permission to create and manage personal access token
- permission to create and manage GitHub Actions workflow
- An AWS account
- administrative permissions for AWS services, such as Amplify, IAM, S3, etc.
- Desktop:
- a local machine with npm, nodejs installed.
- VSCode IDE (Optional, but best to have)
Preparation
Here are some manual preparation work.
1. Create PAT in GitHub Account
Personal access tokens are intended to access GitHub resources on behalf of yourself. With personal access token, you can manage your GitHub source code using Git CLI from local machine. Follow the official tutorial to generate a fine-grained personal access token.
Copy the token and save it somewhere else as the token will gone if the browser is refreshed. The token will be used in the variable ACCESS_TOKEN of Terraform infrastructure, and in Git commands.
2. Create Terraform Backend S3 Bucket
As our application is provisioned using Terraform, we should create a S3 bucket manually from AWS console as the Terraform backend to store state files.
From AWS S3 console. Click on "Create Bucket" button, enter a bucket name with the AWS account id and region to make it unique in the global, for example terraform-state-{aws-account-id}-{aws-region}. The bucket will be used in the environment variable of STATE_BUCKET of Terraform CLI.
3. Create a New GitHub Repository
Create a GitHub repository from GitHub console https://github.com/new. In the demo, I created a repository in my personal GitHub account with name amplify-vue-app as below.
4. Install and Authorize the Amplify GitHub App for Deployment
Before you deploy a new app to Amplify from existing code in a GitHub repo, follow instructions to install and authorize the GitHub App. After completed, Amplify will be granted all necessary permissions to interact with GitHub repository you configured. For example, pull source code, listen on GitHub events, etc.
From GitHub -> Settings -> Integrations -> Applications, a GitHub App as below is installed successfully. You can view and update the Amplify GitHub App from here as needed.
Notes:
If you missed the step, you will be asked to install and authorize the Amplify GitHub App from AWS Amplify console when your Amplify app firstly launched.
If the step is already completed, but the deployment fail with error "[ERROR]: !!! Unable to assume specified IAM Role. Please ensure the selected IAM Role has sufficient permissions and the Trust Relationship is configured correctly", double check if your new repository is in the list of Repository access of above GitHub App.
Scaffolding Vue Project
Step 1. Clone your new repository to local machine. You may be asked for the username and password. The username is the GitHub account username, password is the personal access token (PAT) that generated in Prep 1.
git clone https://github.com/camillehe1992/amplify-vue-app.git
cd amplify-vue-app
Step 2. Scaffolding your Vue project using Vite. See the detailed information from https://vitejs.dev/guide/
npm create vite@latest . -- --template vue
npm install
npm run dev
The Vue project is listening on http://localhost:5173/ as below.
Step 3. Commit the code change and push to remote repository.
git add .
git commit -m "scaffolding vue project"
git push
Now we have setup a simple Vue project.
Setup Terraform Infrastructure
We use Terraform to provision and manage AWS infrastructure, including Amplify App. All Terraform infrastructure related code is under terraform directory. You can find the detailed description of Terraform infrastructure from repository documentation.
.
├── .env.sample # Environment variables for Terraform
├── .terraform-docs.yaml # terraform-docs configuration file
├── .terraform.lock.hcl # Auto generated The dependency lock file
├── Terraform.md
├── amplify.yaml # The build specification for an Amplify app
├── main.tf # Terraform resources definition
├── outputs.tf # Terraform outputs
├── tf_dev.tfvars # Terraform variables for dev env
├── tf_prod.tfvars # Terraform variables for prod env
├── variables.tf # Terraform input variable definition
└── versions.tf # Terraform providers and backend configuration
Provision Terraform Infrastructure using CLI
Terraform provides CLI to manage its infrastructure. See basic Terraform CLI features from official documentation. With Terraform CLI, you can provision AWS infrastructure from local machine or via GitHub Actions workflows.
Option 1. From Local Machine
To provision Amplify infrastructure from local machine, follow the tutorial to setup below configurations:
- Install Terrafrom CLI
- Install AWS CLI
- Configurate AWS Credentials
- Execute Make Commands
After executing make quick-deploy command, an Amplify App named dev-amplify-vue-app is created in AWS Amplify. This Amplify app is for development only, and there is another Amplify app named prod-amplify-vue-app for production environment that will be created using GitHub Actions workflow later.
As you can see, there are two Amplify apps here, which I called Multi-Apps architecture. The architecture simulates the multiple environments in a real project. The production branch in dev-amplify-vue-app is develop, which targets to develop branch in GitHub repository. The production branch in prod-amplify-vue-app is main, which targets in main branch accordingly. In Amplify, each branch has an environment, that maintains in the backend.
In the Multi-Apps architecture solution, when new commits are pushed to the GitHub repository develop branch, a new deployment on the develop branch in Amplify App dev-amplify-vue-app will be triggered automatically. AWS Amplify pulls source code from repository develop branch, then build and deploy it to development environment. After deployment completed successfully, changes in new commits will be available via Amplify app dev-amplify-vue-app default domain url.
Developers can validate the new changes in development environment. If everything works as expected, developers can create a pull request from develop to main branch in repository.
A dedicated branch with prefix pr created for each pull request in Amplify app in the target branch. For example, a pull request from develop to main branch will create a PR branch named pr-2 in prod-amplify-vue-app. No.2 is the order number in GitHub -> Pull Request. Developers can validate the change from the domain url before merging the pull request.
The deployment result and domain url for pull request information is appended in the pull request conversion as below.
Amplify app prod-amplify-vue-app is for production environment, and we disabled the automate build, you should trigger a new deployment from AWS console manually. After completed, the code changes are available in production environment.
Below diagram illustrate the development and deployment workflow in the whole lifecycle.
The benefits of Multi-Apps architecture:
- A dedicated Amplify app for each environment.
- Configuration flexibility on Amplify app for different environments.
- Easy to maintain, easy to scale out (add a new environment, such as testing, or staging).
- Control management, for example, secure Amplify app for production with restricted access if only allowed people or role can manual trigger a new deployment in production environment.
Option 2. Via GitHub Actions
Now, you know how to provision Amplify infrastructure from local machine, and the workflow between GitHub and AWS Amplify. Next, let's create GitHub Actions workflows to automate the Terraform infrastructure provision and management process.
You should be familiar with the concept of Infrastructure of Code (IoC). IaC is the ability to provision and support your computing infrastructure using code instead of manual processes and settings. With Terraform and GitHub Actions, we can provision and manage Amplify infrastructure automatically.
Follow the documentation to provision AWS infrastructure via GitHub Actions workflows.
Demo Project
After provisioning Amplify App prod-amplify-vue-app for production via GitHub Actions workflow, you should get two Amplify App in AWS. Here is the domain url for each environment.
Next Step
Now, we have setup a basic Amplify Multi-Apps architecture solution following infrastructure as code (IaC). You can do some enhancements on top of it, for example,
- Add an Amplify Domain Association resource on Amplify app.
- Add backend resources on Amplify app.
- Add notification process using SNS, CloudWatch Event Bridge, etc, or enable Amplify WebHook.
- Refactor the Single-Account Multi-Apps solution as needed, for example, a dedicated AWS account for Amplify app for specific development. With the Multi-Accounts solution as below, you can grant different permissions for users or roles for best practice. It's suitable to setup an central platform that provisions and manages extensible, Full-Stack Web and Mobile Apps powered by AWS Amplify service in enterprise scope, and integrates with other frameworks or tools to provide one-stop service.
Summary
In the end, you have learned:
- How to setup a Vue based frontend template project from scratch.
- How to define and manage AWS infrastructure using Terraform.
- How to provision and manage AWS infrastructure via GitHub Actions workflow.
Thanks for reading and looking forward to your ideas and comments.
Happy learning, and happy coding!
Top comments (1)
awesome blog post thank you