Install

This page describes how to install the app for testing and how to setup the backend if you wish to create your own backend.

NOTE: If you are only interested in installing the app on a phone or emulator and using our existing backend, you may skip section 1 and follow the instructions in section 2 for setting up the app on your phone or emulator.

NOTE: If you have no interest in setting up the project from the ground up, you may also download the APK and install directly it onto your Android phone here

1. Set up the API server / backend

1.1 Create EC2 Instance

• Click "Launch Instance". You will be redirected to the "Quick Start" tab

• Select "Free tier only" on the left side of the screen

• Select "Amazon Linux 2 AMI (HVM), SSD Volume Type"

• The t2.micro that is free tier eligible should be automatically selected. Click Review and Launch

• Leave all settings as default and click "Launch"

• Create a new key pair (see below)

1.2 Create a Key Pair

• Click "Create new key pair"

• Name your key pair (e.g. amazonadonaAPI)

• Click "Download key pair"

• Select "Launch instances" and wait for your instance to be launched

• Select "View instances" to go to your EC2 dashboard

1.3 SSH into Your Instance

• Cd to where your key pair is downloaded

• Run chmod 400 <keypairName>.pemwhere <keyPairName> is replaced with your downloaded keypair name

• In your EC2 dashboard, copy the "Public DNS (IPv4)". This is the address we will ssh to

• Run the following command ssh -i "<keypairName>.pem" <publicDNS> where <keyPairName> is replaced with your downloaded keypair name, and <publicDNS> is replaced with the address copied in the step above. For example: ssh -i "kee-per.pem" [e-mail]

1.4 Set Up Your Instance

• First we need to install NVM (Node Version Manager) to install Node. Run

  curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.2/install.sh | bash

• Log out and log back into your EC2 instance

• Run nvm --version to make sure NVM was installed properly

• Now run nvm install node to install node

• Install git by running sudo yum install git

• Install screen by running sudo yum install screen

• Install pm2 by running npm install pm2 -g

1.5 Cloning the Repository

• In the home directory (or wherever you want the repository to live run git clone https://github.com/MadeWithPaper/Amazonadonna.git

• Cd into the folder

1.6 Opening the Needed Ports

• In the EC2 dashboard, find your instance and scroll to the right until you find the "Security Groups" column. Click the group name (launch-wizard-1 or something similar)

• On the lower half of the screen, select the "Inbound" tab

• Add a new custom TCP rule with port range 3000 and accessible from everywhere (0.0.0.0/0)

1.7 Installing ngrok

• Android only lets us make API calls to URL's secured with SSL. Since we don't want to buy a domain / SSL certificate, we use a tunneling service called ngrok to get around this

• Go to https://ngrok.com/ and create an account

• Once logged in follow the 4 instructions to download, install, and connect your account. I recommend using scp to upload the file to your ec2 instance. Ngrok is a little weird since you don't add it to your PATH, so I would put it in your home folder so you can access it easily

• Don't worry about starting it up just yet

1.8 Starting ngrok

• We will use screen, a utility to let programs runs even once we disconnect from the shh instance

• Run screen

• Now we can start ngrok, so navigate to your home directory or wherever ngrok is and run ./ngrok http 3000

• You should see ngrok start and list 2 urls. We want the https url, so copy the one that looks something like https://99956a2e.ngrok.io

• This is the URL we will use to talk to the API. This url will change every time you restart ngrok unless you pay, so to avoid having to constantly change the URL on the frontend its best if you just leave ngrok running

• Disconnect from screen by typing Ctrl+a d

• Ngrok will continue to run in the background. If you ever need to get back to this screen, type screen -r

1.9 Set up DynamoDB

• Set up a new DynamoDB instance on AWS. We used all the default settings

• Create the following tables, and make sure the "Partition key" for each entry matches exactly

• Add the following indexes for each table. All settings were left as default, and all indexes are GSI type

  • artisan: (cga-index, partition key: cgaId)

  • item: (artisanId-index, partition key: artisanId)

  • order: (cga-index, partition key: cgaId)

  • orderitem: (orderId-index, partition key: orderId), (itemId-index, partition key: itemId)

  • payout: (cga-index, partition key: cgaId), (artisanId-index, partition key: artisanId)

1.10 Set up S3

• Create 3 buckets (note: you won't be able to use these same bucket names, but name yours something similar):

  • artisan-item-pics

  • artisan-prof-pics

  • payout-signatures

• Use default settings, but on step 3, "Set permissions", uncheck every box for all 3 buckets

• Change the updateImage routes in item, artisan, and payout routes to use your bucket names in the multerS3 settings

1.11 Starting the App

• Back on the server, cd into the API directory under the Amazonadonna folder.

• Run npm i to install all of the required node packages

• Run pm2 start npm --name "server" -- run-script start:prod

• Run pm2 startup

• Copy the output from the previous command and run it

• Finally, run pm2 save

• pm2 is used to keep the server running if we disconnect from ssh / restart the EC2 instance. We told it to run our npm script to start the server, npm run-script start:prod (which is useful for starting the server manually when you are debugging). To stop the running server, run pm2 stop alland to start it back up runpm2 restart all

1.12 Copy ngrok URL to frontend

• In android studio, be sure to keep all of the API calls up to date with the current ngrok url!

1.13 Dev Environment / Notes

• I highly recommend using VS Code to edit the backend, and if you open the API folder in VS Code we have certain settings checked in that Code will recognize automatically

• If you want to test locally, run npm start(after running npm i to install the packages locally). Its hard to access dynamodb locally, but this will at least let you know if you have any compile errors

• Otherwise, right now our dev flow is to commit to a branch, check it out on the server, stop the currently running server with pm2 stop all, run npm run-script start:prod to test, and once it is good we merge with master, checkout master on the server, and run pm2 restart all

2. Install the Application on to your device (phone or emulator on a computer)

Emulator on a computer

1. Download Android Studio from (https://developer.android.com/studio)

2. Install Android Studio following on screen instructions

3. Download the our code base from our GitHub (https://github.com/MadeWithPaper/Amazonadonna)

   1. Your can choose to download the zip file or

   2. Clone the repository from command line

4. Register for Login with Amazon by following instructions here. Only complete up to 'Add Android Settings to your Security Profile'.

   1. Obtain your MD5 and SHA256 signatures by doing the following.

      1. Open project in Android Studio.

      2. Click the "Gradle" tab in the top-right corner.

      3. Expand your 'app' directory.

      4. Expand 'tasks' directory.

      5. Expand 'Android' directory.

      6. Double click on 'signing report'.

      7. Signatures will print in the status area of the IDE.

   2. Once you have obtained the api key by following the above instructions, place the key in 'app/src/main/assets/api_key.txt'.

5. Start Android Studio

6. Click "Open an existing Android Studio Project"

7. Locate the location where you have saved the code base (This is usually indicated by the Android Studio Icon next to the file)

8. Select the project files, Click OK

9. Now we must create an Android Emulator, Tools > AVD Manager > Click "Create Virtual Device"

10. Select "Phone" from Category, Select the latest device from the list, Click "Next"

11. Select the Android OS Version you want (we recommend the latest version)

    1. You may need to download the system image before proceeding, Click the Download button next to the Version of Android you wish to run on your emulator, following the on screen instructions

12. Click next after you have selected an Android OS system image

13. Click Finish, Close out of "Your Virtual Devices"

14. Click "Run" on the top menus > Run "app" > Select the emulator you have created in the previous steps, Click "OK"

15. An Android Emulator starts up with the app running

Phone

1. Download our app's APK here

   1. if you downloaded it on your computer, please transfer the APK file to your phone

2. Find the APK file within your phone's file system

3. Click on the APK this will start the install process on the phone

   1. If prompted to enable "allowed to install unknown apps from this source"

   2. Click settings

   3. Tap the slider to turn on "Allow from this source"

   4. Tap the device back button to return to install process

4. Tap Install (The app will be installed to the phone)

5. Tap Open

6. This will open the application.

If you ran into any problems with the installation process, please Contact us