Remote Development with Visual Studio Code on AWS EC2

The following will show you how to create and connect to a virtual machine (VM) on AWS using the Visual Studio Code Remote - SSH extension. You'll be able to run Telescope in development on a remote machine with VS Code just like if the source code was local. This documentation is based on Remote development over SSH

Telescope is a tool for tracking blogs around Seneca's open source develop. The application itself has many microservices that use Docker containers and are composed together using Docker-Compose. You can find the GitHub repo here

Telescope Tech Stack

• Next.js
• Material UI
• Node.js
• Elasticsearch
• Redis
• Traefik
• Nginx
• Docker
• Supabase
• Jest

Telescope Microservices

• Dependency Discovery
• Feed Discovery
• Image
• Parser
• Planet
• Posts
• Search
• SSO
• Status
• Users

Disclaimer: This guide is specifically designed for students who are enrolled in AWS Academy so the services and technologies used adhere by the AWS Academy Learner Lab - Foundation Services restrictions.

Note: If you are not enrolled in AWS Academy, please note that the EC2 instance used in this guide is not within AWS's Free-Tier so please see EC2 Pricing to see if you're comfortable with these costs.

Running Docker in development is CPU intensive so these are the EC2 instances I recommend:

• Minimum: t2.large (8 GiB RAM + 2 vCPU)
• Recommended: r5.large (16 GiB RAM + 2 vCPU)

Summary of Pricing:

• t2.large costs \$0.0928 per hour
• r5.large costs \$0.126 per hour
• 20GB Amazon Elastic Block Storage (EBS) costs \$1 per month
• Elastic IP Address

Cost Estimate Per Month:

Prerequisites:

• Download and install Visual Studio Code
• Install the Remote - SSH extension
• AWS Academy Account. You will need your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY and your SSH key (.pem file)

Create your virtual machine (AWS EC2):

1. In the upper-right hand corner of your AWS Management Console, select a region. In this tutorial, US East (N. Virginia) us-east-1 as your Region

1. In the search bar at the top, type in ec2 and click on EC2 to go to the EC2 Dashboard
2. Click on Launch instances

• Step 1 - Choose an Amazon Machine Image (AMI): Amazon Linux 2 AMI (HVM) - Kernel 5.10, SSD Volume Type
• Step 2 - Choose an Instance Type: r5.large
• Step 3 - Configure Instance Details:
  • IAM role: LabInstanceProfile
  • Copy and paste the aws-userdata.sh script into the User data field
• Step 4 - Add Storage: Change the Size (GiB) from 8 to 20
• Step 5 - Add Tags: No tags are needed. Proceed to the next step.

• Step 6 - Configure Security Group:

  • Assign a security group: Create a new security group
  • Security group name: telescope-sg
  • Add the following Rules:
  • SSH for your IP address
  • Type: SSH
  • Protocol: TCP
  • Port Range: 22
  • Source: My IP (When you select this from the dropdown menu, it will automatically put <your-ip-address>/32 in the field. For example 76.72.29.150/32)
  • Open port 3000 for your IP address
  • Type: Custom TCP
  • Protocol: TCP
  • Port Range: 3000
  • Source: My IP
  • Open port 8000 for your IP address
  • Type: Custom TCP
  • Protocol: TCP
  • Port Range: 8000
  • Source: My IP
  • Open port 8000 for your IP address
  • Type: Custom TCP
  • Protocol: TCP
  • Port Range: 8443
  • Source: My IP

Note: My IP is the IP address of your (home) network. Your IP address will likely change if you manually reboot your router or a power outage occurs and your router reboots itself. If you know your IP address has changed, please update the Security Group on AWS.

1. Click on Review and Launch. You will get a warning: Your instance configuration is not eligible for the free usage tier, this is because we're using a r5.large instance type.
2. Click on Launch
3. In the pop-up, choose Choose an existing key pair

• Select a key pair: vockey

1. Click on Launch Instances

It will take a few minutes for AWS to launch your new EC2 instance.

1. Once your EC2 instance has been launched, you should name it something meaningful like Telescope-Dev and you can find your EC2 instance's public IPv4 address. Make note of this IP address.

Associate an Elastic IP address to your EC2 instance

1. In the left-hand pane, go to Network & Security > Elastic IPs
2. Click on Allocate Elastic IP address button

• Network Border Group: us-east-1
• Public IPv4 address pool: Amazon'pool of IPv4 addresses and click on Allocate

1. Select the newly created Elastic IP address. In the Actions dropdown menu, select Associate Elastic IP address
2. Select the EC2 instance you've created in the previous section Telescope-Dev and click on Associate
3. In the left-hand pane, go to Instances, select Telescope-Dev and you should be able to see that your Elastic IP address has been associated to your EC2 instance

Connect using SSH

Obtain your AWS Credentials and SSH Key

1. You can find your AWS credentials under AWS Details of your AWS Academy account

2. Download the SSH key (labsuser.pem) file to your local computer. Note the file location

3. Open up Visual Studio Code

4. Click on the Open a Remote Window icon at the bottom left-hand corner of the window
   

5. Select Connect to Host
   

6. Select Configure SSH Hosts...
   

7. This will open up a config file in Visual Studio Code. If you're using Windows, it'll be something like C:/Users/cindy/.ssh/config
   

8. Edit the config file with the following:
   

Host aws-e2
    HostName <your-ec2-ip-address>
    User ec2-user
    IdentityFile ~/.ssh/labsuser.pem

1. Save the file
2. When you click on the Open a Remote Window icon at the bottom left-hand corner again and choose Connect to Host, you will see aws-ec2 listed.
3. Select aws-ec2 and a new Visual Studio Code window will open.
4. You will see "aws-ec2" has fingerprint "SHA256:xxx" and Are you sure you want to continue?. Click on Continue. Then You should see that you're connected!

Setting up your AWS credentials

1. Open up a terminal in Visual Studio Code (hotkey on Windows: Ctrl + backtick). You should see that you're logged in as something like [ec2-user@ip-172-31-4-0 ~]$.

2. Verify the AWS CLI installation
   

$ aws --version

aws-cli/2.3.0 Python/3.8.8 Linux/5.4.0-1045-aws exe/x86_64.ubuntu.20 prompt/off

1. Configure your AWS credentials

aws configure

1. Currently, everything is set as None so enter your credentials for your AWS IAM user.

AWS Access Key ID [None]: ****************764G
AWS Secret Access Key [None]: ****************qBbe
Default region name [None]: us-east-1
Default output format [None]:

Verify that everything in the aws-userdata.sh script was installed correctly

1. Check Docker: docker info
2. Check docker-compose version: docker-compose --version
3. Check Node.js version: node -v
4. Check pnpm version: pnpm -v
5. Check git version: git --version

Authenticate as your GitHub account with the GitHub CLI

1. Run gh auth login
2. What account do you want to log into? GitHub.com
3. What is your preferred protocol for Git operations? SSH
4. Generate a new SSH key to add to your GitHub account? Yes
5. Enter a passphase for your new SSH key (Optional): ********
6. How would you like to authenticate GitHub CLI? Login with a web browser
7. First copy your one-time code: ABC1-234D

Opening up the Telescope repository in AWS EC2:

1. Clone your fork of the Telescope repository. For example gh repo clone cindyledev/telescope. If you do not have a fork of the Telescope repository, run gh repo clone -o upstream Seneca-CDOT/telescope to clone the Telescope repository and name the remote upstream then proceed to Step 5.

gh repo clone <github-username>/telescope

1. Open the telescope directory and the entire Telescope files and folder structure should be visible to you!
   
   

2. Add the Telescope repository and name the remote upstream by entering
   

git remote add upstream https://github.com/Seneca-CDOT/telescope.git

1. Verify that the remote has been added

git remote -v

1. Set all the necessary environment variables in your .env file to contain your EC2 instance's public IPv4 address by executing the aws-ip.sh script

sh ./tools/aws-ip.sh

If you did everything correctly, you've completed the environment setup!

Now to get started with development...

1. Install all dependencies

pnpm install

1. Start all Telescope services using the environment variables set in .env. This will take some time to complete

Note: Do not use pnpm services:start. This will use the environment variables in config/env.development and we don't want that here.

docker-compose --env-file .env up -d

1. Start the Telescope development server on Port 3000

pnpm start

1. Find your EC2 instance's public IPv4

$ curl -s http://169.254.169.254/latest/meta-data/public-ipv4

35.174.16.133

1. Open <public-ip>:8000 browser tab to see Telescope running on a AWS Cloud9 environment!

2. Open <public-ip>:3000/feeds in another browser tab to see all the feeds in the backend

3. Open <public-ip>:8443/v1/<microservice-port> in another browser tab to see the microservices. For example 35.174.16.133:8443/v1/status

Frequently Asked Questions (FAQ)

How do I stop my docker containers?

pnpm services:stop

How do I delete my docker containers?

docker system prune -af --volumes

I can't open <EC2-ip>:8000 running, what could I be doing wrong?

1. If you have a VPN on, turn it off and get your IP address by visiting http://checkip.amazonaws.com/ then updating your Security Group to allow your IP address to access the ports 22, 3000, 8000, and 8443.

2. Your home IP address may have changed because your router was rebooted. This can happen when you manually reboot your router or when a power outage occurs. The solution here is the same as above. You can get your IP address by visting http://checkip.amazonaws.com/ then updating your Security Group to allow your IP address to access the ports 22, 3000, 8000, and 8443.

How do I turn off my EC2 instance if I'm actively not using it?

1. Close your Remote Connection on VS Code

2. Manually turning the EC2 instance off using the AWS Console
   

3. Stop your AWS Academy Lab