AWS Amplify CLI Installation Guide (M1/M2 2022 Mac Edition)

#aws #cloud #serverless #node

💭 What is the AWS Amplify Framework?

One of my absolute favorite frameworks for building cloud-based, serverless applications is the AWS Amplify framework. I have been spending the better part of this past year learning the ins-and-outs of the framework, as well as extending each of the tools in the tech stack to incorporate new integrations, data models, front-end experiences, and event-driven architectures.

This framework, to me, really conceptualizes what makes serverless applications so powerful. Within the framework, you leverage the @aws-amplify CLI (command line interface) to provision resources in the cloud right from the command line. Most importantly, these resources are deployed with the right IAM (Identity and Access Management) authorization rules and abide by the AWS principle of "Least Privileged Access".

Some examples of these great CLI commands include:

amplify add auth: configure an AWS Cognito User Pool and methods for signing-in, including email/password and/or social federation (i.e. Facebook, Apple, OpenID, SAML, etc.)
amplify add api: configure an AppSync API via REST or GraphQL that configures directly to a NoSQL DynamoDB database to read/write from the front-end to your back-end.
amplify add storage: configure AWS S3 file upload/download capabilities for files, such as images, videos, PDFs, music files, etc.
amplify add hosting: configure a manual deployment or CI/CD (continuous integration/continuous deployment) pipeline to deploy your app's code to an amplify URL or your own custom domain.
amplify status: review your locally deployed AWS resources before you deploy them.
amplify push: run a cloudformation script to deploy your locally created AWS resources to your cloud environment.

Case in point, the AWS Amplify framework is a great wrapper around core AWS services and their functionalities to help you build faster, without compromising security or scalability.

⚠️ 2022 Update on Installing the AWS Amplify CLI

Migrating to new technology, like a new laptop or OS, can be a very daunting process. Setting up my new M1 Max laptop this year was a process that took a couple weeks, myself. You will find out how many CLIs, SDKs, softwares, systems, and tools that installed once and forgotten 😊

What can be especially frustrating when moving from one OS to another, such as the 2019 MacBook Pro to the 2022 M1 Max, is when the tools you use on the previous device don't work the same on the new one. This happened with installing the @aws-amplify CLI.

I ran into a core issue where I needed to use sudo in front of all of the AWS Amplify CLI commands, which meant I would have to put in my password EVERY SINGLE TIME I ran amplify something 🙃

I hope that this guide helps you get up and running with AWS Amplify, especially if you run into the Error: EACCES: permission denied errors that I ran into.

Installation Guide

For reference, the AWS Amplify steps referenced below are also viewable on the Amplify Docs here should there be any differences or modifications since the writing of this blog.

🧑‍💻 Step 1: Installing Node.js and npm

Node.js, also referred to NodeJS or just Node, is an open-sourced and widely adopted JavaScript runtime environment. When you are running a JavaScript server, NodeJS is often what is being referenced.

On the homepage, NodeJS will attempt to read the type of device you have and then present two download options for you:

I've found that the LTS version is the one that works most of the time, so I installed that one.

When you install NodeJS, you will also have the option to install npm (Node Package Manager) as well. Make sure that option is selected if there is an option, as you will need npm when installing dependencies in your projects or running node scripts.

⚠️ IMPORTANT: if you have any issues installing NodeJS or npm on your Mac, Homebrew.sh may be helpful to you. When you install Homebrew, it helps you package your installations into their own directory and them symlinks them to usr/local on your Mac.

🧑‍💻 Step 2: Set up an AWS Account

On the AWS homepage you will see a bright orange button in the top right that says "Create an AWS Account."

To set up an account, you will need an email and a credit card, but don't worry, you will only be charged a temporary ~$1 (or less) hold to verify your card. It will be refunded to you within 1-3 business days.

🧑‍💻 Step 3: Installing the Amplify CLI

The AWS Amplify CLI (command line interface) is a set of programmable terminal scripts to create/deploy AWS services for any application, website, or system.

There are 3 core ways to install the @aws-amplify CLI:

npm (for NodeJS users):

npm install -g @aws-amplify/cli

cURL (for Mac/Linux):

curl -sL https://aws-amplify.github.io/amplify-cli/install | bash && $SHELL

cURL (Windows-only):

curl -sL https://aws-amplify.github.io/amplify-cli/install-win -o install.cmd && install.cmd

The immediate go-to since we just installed NodeJS/npm would be to install via the npm install... command.

So let's do that!

🧑‍💻 Step 3.5: If you receive `Error: EACCES: permission denied` errors after running the above.

In the latest models of the Apple M1/M2 Macbook Pro/Max's, there is well documented issues around installing system-wide software and tools where the Mac will reject installing it, claiming access permission issues.

This is what that might look like if you receive this error after running: npm install -g @aws-amplify/cli

npm WARN config global `--global`, `--local` are deprecated. Use `--location=global` instead.
npm ERR! code EACCES
npm ERR! syscall rename
npm ERR! path /usr/local/lib/node_modules/@aws-amplify/cli
npm ERR! dest /usr/local/lib/node_modules/@aws-amplify/.cli-XXXXXXXX
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, rename '/usr/local/lib/node_modules/@aws-amplify/cli' -> '/usr/local/lib/node_modules/@aws-amplify/.cli-XXXXXXXX'
npm ERR!  [Error: EACCES: permission denied, rename '/usr/local/lib/node_modules/@aws-amplify/cli' -> '/usr/local/lib/node_modules/@aws-amplify/.cli-XXXXXXXX'] {
npm ERR!   errno: -13,
npm ERR!   code: 'EACCES',
npm ERR!   syscall: 'rename',
npm ERR!   path: '/usr/local/lib/node_modules/@aws-amplify/cli',
npm ERR!   dest: '/usr/local/lib/node_modules/@aws-amplify/.cli-XXXXXXXX'
npm ERR! }
npm ERR! 
npm ERR! The operation was rejected by your operating system.
npm ERR! It is likely you do not have the permissions to access this file as the current user
npm ERR! 
npm ERR! If you believe this might be a permissions issue, please double-check the
npm ERR! permissions of the file and its containing directories, or try running
npm ERR! the command again as root/Administrator.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/MYUSER/.npm/_logs/2022-10-15T17_42_00_235Z-debug-0.log

✅ PART 1: A temporary workaround is install the amplify CLI with sudo if you can't install with just npm. Sudo is an admin-only command to install something globally

sudo npm install -g @aws-amplify/cli

In the long-term if left like this, it will present a nightmare of permission issues where you will have to enter your admin password every single time you want to run an amplify command (after a month of this madness, I needed to figure out how to stop the madness). So continue to the following step on how to switch the amplify CLI to be accessible by your device user.

✅ PART 2: Now that the amplify CLI is installed via sudo, we now must configure the CLI to be accessible to our specific user. What we did in the above was make the amplify cli accessible only to our root user, not our device user.

We will use a bit of linux to change the owner for our amplify CLI toolchain. In a new terminal window, run the following commands one by one, and make sure to replace MYUSER with the user of your device. You can find out what the name is by opening a separate terminal window and running whoami and what is printed out is your device name.

# invoke a root shell by logging in as the root user
sudo -i

# change directory into your specific user you want to adjust
cd ~MYUSER

# change ownership of the `.amplify` file to MYUSER
chown -R MYUSER .amplify

What we just did was change the ownership of the hidden directory .amplify installed under our user. If you want to find where this is, run ls -al and you should see a list of directories, including .amplify

✅ PART 3: Test
In a separate terminal window, check if you can run amplify help. If you get a response back and the CLI is running the help command, then you are all installed correctly!