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
- Firebase
- Jest
Telescope Microservices
- Auth
- Feed-Discovery
- Image
- Parser
- Planet
- Posts
- Search
- Status
- Users
Disclaimer: 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.medium (4 GiB RAM + 2 vCPU)
- Recommended:
t2.large (8 GiB RAM + 2 vCPU)
Summary of Pricing:
- t2.medium costs \$0.0464 per hour
- t2.large costs \$0.0928 per hour
- 30GB Amazon Elastic Block Storage (EBS) costs \$3 per month
Cost Estimate Per Month:
t2.medium | t2.large | |
---|---|---|
Cost per hour | \$0.0464 | \$0.0928 |
Hours per day | 8 | 8 |
Days per month | 30 | 30 |
Sub-total | \$11.14 | \$22.27 |
30GB EBS Volume | \$3 | \$3 |
Total | \$14.14 | \$25.27 |
Prerequisites:
- Download and install Visual Studio Code
- Install the Remote - SSH extension
- Create an AWS Account. You can watch this part of the AWS Certified Cloud Practitioner course on creating an account if you need help.
- Create an IAM user with administrative privileges. You will need your
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
- Sign into your AWS Account using your IAM user
Create your virtual machine (AWS EC2):
- In the upper-right hand corner of your AWS Management Console, select
US East (Ohio) us-east-2
as yourRegion
- In the upper-left hand corner of your AWS Management Console, click on
Services
. This will bring up a list of AWS Services, search forEC2
- Click on
Launch instances
- Step 1 - Choose an Amazon Machine Image (AMI):
Ubuntu Server 20.04 LTS (HVM), SSD Volume Type
- Step 2 - Choose an Instance Type:
t2.medium
- Step 3 - Configure Instance Details: Accept the defaults and proceed to the next step
- 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:
- 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 at2.medium
instance type. - Click on
Launch
- In the pop-up, choose
Create a new key pair
- Key pair type:
RSA
- Key pair name:
telescope-dev-key
- Click on
Download Key Pair
- If you're using Windows, save the file in the
.ssh
directory in your user profile folder (for exampleC:/Users/cindy/.ssh/
) - 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.
Connect using SSH
- Open up Visual Studio Code
- Click on the
Open a Remote Window
icon at the bottom left-hand corner of the window - Select
Connect to Host
- Select
Configure SSH Hosts...
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-ec2
HostName <your-ec2-ip-address>
User ubuntu
IdentityFile ~/.ssh/telescope-dev-key.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 likeubuntu@ip-172.31.23.4
.Install
unzip
. We will need this to install the AWS CLI
$ sudo apt install unzip
- Install the latest version of the AWS CLI
$ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
- 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
- Remove the
awscliv2.zip
file andaws
directory
rm awscliv2.zip
rm -rf aws
- 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-2
Default output format [None]:
Installing Docker and Docker-Compose
Install Docker Engine - Community Edition
- Update the apt package index:
sudo apt-get update
- Install packages to allow apt to use a repository over HTTPS:
sudo apt-get install \
ca-certificates \
curl \
gnupg \
lsb-release
- Add Docker’s official GPG key:
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
- Use the following command to set up the stable repository:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
- Update the apt package index again:
sudo apt-get update
- Install the latest version of Docker Engine community:
sudo apt-get install docker-ce docker-ce-cli containerd.io
- Add your user to the Docker group (source):
sudo usermod -aG docker $USER
- Activate the changes to groupss
newgrp docker
- Now run docker as a service on your machine, on startup:
- Enable docker on startup:
sudo systemctl enable docker
- Disable docker on startup:
sudo systemctl disable docker
Install Docker-Compose
- Run to download the current stable version of Docker-Compose:
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
- Apply executable permissions to the downloaded file:
sudo chmod +x /usr/local/bin/docker-compose
- Check installation using:
$ docker-compose --version
docker-compose version 1.29.2, build 5becea4c
Install Node.js and npm
- Install Node.js 16.x and npm 8.1
$ curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs
- Verify installation
$ node -v
v16.12.0
$ npm -v
8.1.0
Setting up the Telescope repository in AWS EC2:
- Clone the Telescope repository and name the remote
upstream
by entering
git clone -o upstream https://github.com/Seneca-CDOT/telescope.git
Open the
telescope
directory and the entire Telescope files and folder structure should be visible to you!
Set all the necessary environment variables in your env.remote 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
npm install
- Start all Telescope services. This will take some time to complete
docker-compose --env-file .env up -d
- Start the Telescope development server on Port 3000
npm 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/posts
Frequently Asked Questions (FAQ)
How do I stop my docker containers?
npm run services:stop
How do I delete my docker containers?
docker system prune -af --volumes
I get Permission denied
error when I run docker-compose --env-file .env up -d
Sometimes the Docker permissions aren't set properly when you first install Docker. You may need to reboot your VM or run
newgrp docker
I can't open :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 allow your IP address to access the ports 3000 and 8000.
AWS may change your EC2 instance IP address when you stop or restart your EC2 instance. One solution is to purchase an Elastic IP address to reserve the particular public IP address. However, you can just clean out the
env.remote
and.env
files and run the./tools/aws-ip.sh
script again to set your new EC2 IP address in the appropriate environment variables. Just remember to use the new EC2 IP address in the browser as well.
I can't SSH into my EC2 instance
- Same reason as above, your EC2 instance IP address may change when you stop or restart your EC2 instance. So make sure your
.ssh/config
file has the correct HostName - If your own IP address changes (for example, you changed internet providers or you moved to a new location with a different IP address), you need to update your inbound rules to allow your IP address to access port 22. Don't forget to allow access to port 3000 and 8000 as well.
How do I turn off my EC2 instance if I'm actively not using it?
There are a number of different methods to stop an EC2 instance:
-
Creating a Cloudwatch alarm to stop your EC2 instance for you after some inactivity
- Click on the
+
underneathAlarm status
to start creating an alarm - Click on
Create an alarm
radio button - Set
Alarm action
toStop
- Set alarm to trigger if the CPU utilization of the EC2 instance has been less 25% for an hour
- Click on the
Top comments (0)