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:
t2.large | r5.large | |
---|---|---|
EC2 Instance cost per hour | \$0.0928 | \$0.126 |
Elastic IP Address cost per hour | \$0.005 | \$0.005 |
Hours per day | 6 | 6 |
Days per month | 30 | 30 |
Sub-total | \$17.60 | \$23.58 |
20GB EBS Volume | \$0.5 | \$0.5 |
Total | \$18.10 | \$24.08 |
Prerequisites:
- Download and install Visual Studio Code
- Install the Remote - SSH extension
- AWS Academy Account. You will need your
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
and your SSH key (.pem
file)
Create your virtual machine (AWS EC2):
- 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 yourRegion
- In the search bar at the top, type in
ec2
and click onEC2
to go to the EC2 Dashboard - 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
to20
- 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 example76.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
- Assign a security group:
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.
- 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 ar5.large
instance type. - Click on
Launch
- In the pop-up, choose
Choose an existing key pair
- Select a key pair:
vockey
- Click on
Launch Instances
It will take a few minutes for AWS to launch your new EC2 instance.
- 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
- In the left-hand pane, go to
Network & Security
>Elastic IPs
- Click on
Allocate Elastic IP address
button
- Network Border Group:
us-east-1
- Public IPv4 address pool:
Amazon'pool of IPv4 addresses
and click onAllocate
- Select the newly created Elastic IP address. In the
Actions
dropdown menu, select Associate Elastic IP address - Select the EC2 instance you've created in the previous section
Telescope-Dev
and click onAssociate
- In the left-hand pane, go to
Instances
, selectTelescope-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
- You can find your AWS credentials under
AWS Details
of your AWS Academy account Download the
SSH key
(labsuser.pem) file to your local computer. Note the file locationOpen up Visual Studio Code
Click on the
Open a Remote Window
icon at the bottom left-hand corner of the window
This will open up a
config
file in Visual Studio Code. If you're using Windows, it'll be something likeC:/Users/cindy/.ssh/config
Edit the
config
file with the following:
Host aws-e2
HostName <your-ec2-ip-address>
User ec2-user
IdentityFile ~/.ssh/labsuser.pem
- Save the file
- When you click on the
Open a Remote Window
icon at the bottom left-hand corner again and chooseConnect to Host
, you will seeaws-ec2
listed. - Select
aws-ec2
and a new Visual Studio Code window will open. - You will see
"aws-ec2" has fingerprint "SHA256:xxx"
andAre you sure you want to continue?
. Click onContinue
. Then You should see that you're connected!
Setting up your AWS credentials
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 ~]$
.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
- Configure your AWS credentials
aws configure
- 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
- Check Docker:
docker info
- Check docker-compose version:
docker-compose --version
- Check Node.js version:
node -v
- Check pnpm version:
pnpm -v
- Check git version:
git --version
Authenticate as your GitHub account with the GitHub CLI
- Run
gh auth login
- What account do you want to log into?
GitHub.com
- What is your preferred protocol for Git operations?
SSH
- Generate a new SSH key to add to your GitHub account?
Yes
- Enter a passphase for your new SSH key (Optional):
********
- How would you like to authenticate GitHub CLI?
Login with a web browser
- First copy your one-time code:
ABC1-234D
Opening up the Telescope repository in AWS EC2:
- 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, rungh repo clone -o upstream Seneca-CDOT/telescope
to clone the Telescope repository and name the remoteupstream
then proceed to Step 5.
gh repo clone <github-username>/telescope
Open the
telescope
directory and the entire Telescope files and folder structure should be visible to you!
Add the Telescope repository and name the remote
upstream
by entering
git remote add upstream https://github.com/Seneca-CDOT/telescope.git
- Verify that the remote has been added
git remote -v
- 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...
- Install all dependencies
pnpm install
- 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
- Start the Telescope development server on Port 3000
pnpm start
- Find your EC2 instance's public IPv4
$ curl -s http://169.254.169.254/latest/meta-data/public-ipv4
35.174.16.133
Open
<public-ip>:8000
browser tab to see Telescope running on a AWS Cloud9 environment!Open
<public-ip>:3000/feeds
in another browser tab to see all the feeds in the backendOpen
<public-ip>:8443/v1/<microservice-port>
in another browser tab to see the microservices. For example35.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?
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.
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.
Top comments (2)
Nice Article! very detailed step by step, Im going to try
Nice work!