Setup

By the end of this page, you should be able to run the starter program and view its SVG drawing. You do not need to change any source code yet.

The AWS instance is a remote computer. Run the AWS CLI and SSH setup commands on your laptop; switch to the instance at Building and Running below.

AWS Access

You should have received an email titled “CS152 Lab 5 AWS Access”. This email contains the following important information:

  • Access Key ID
  • Secret Access Key ID
  • Region
  • SSH Key
  • Instance ID

This information is necessary to complete the following setup and access an AWS Instance to run this lab. Replace brace-delimited placeholders with the values supplied for your instance.

Get Your Student Repository

In your laptop browser, accept the GitHub invitation to ucb-152, then log in to Classroom50 with your Berkeley email and select the CS152 Fa26 classroom. Accept the Lab 5 assignment to create your student repository from the template. Copy its SSH URL for cloning later.

AWS CLI Setup

Install the AWS CLI, then configure the lab profile using the command below:

aws configure --profile cs152

The Access Key ID, Secret Access Key ID, and Region come from the email. Leave the output format blank.

Session Manager Plugin

Your instance has no fixed public address. SSH connects to it through AWS Session Manager instead, using your Instance ID as the host name. Install the Session Manager plugin for the AWS CLI on your laptop. On macOS with Homebrew:

brew install --cask session-manager-plugin

Check that it is installed:

session-manager-plugin --version

SSH Setup

On your laptop, download the attached SSH key to your Downloads folder. Replace KEY_FILENAME below with the downloaded filename (without braces), then move the key into ~/.ssh/ and restrict its permissions:

mkdir -p ~/.ssh
mv ~/Downloads/KEY_FILENAME ~/.ssh/
chmod 400 ~/.ssh/KEY_FILENAME

Add this entry to ~/.ssh/config:

Host graviton_cs152
    HostName {INSTANCE_ID}
    User ubuntu
    IdentityFile ~/.ssh/{KEY_FILENAME}
    ServerAliveInterval 60
    ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p --profile cs152 --region {REGION}"

On Windows, replace the ProxyCommand line with:

    ProxyCommand C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p --profile cs152 --region {REGION}"

ssh, scp, and VS Code Remote SSH all use this entry, so they all connect through Session Manager.

Starting and Stopping the Instance

Start the instance using the provided Instance ID, wait about a minute for it to boot, and connect:

aws ec2 start-instances --instance-ids {INSTANCE_ID} --profile cs152
ssh graviton_cs152

If SSH reports TargetNotConnected, the instance is still booting; wait 30 seconds and try again. If start-instances reports IncorrectInstanceState, the instance is still stopping from your last session; wait a minute and try again.

When you take a break or finish working, leave the SSH session with exit, then stop the instance from your laptop:

aws ec2 stop-instances --instance-ids {INSTANCE_ID} --profile cs152

The lab instance shuts down after more than 45 minutes of near-zero CPU use, even while an SSH or VS Code session is open. Stop it yourself rather than relying on that timeout.

Building and Running

After connecting with ssh graviton_cs152, clone your student repository on the remote Ubuntu Arm instance and run its setup script there. Run all commands in this section on your instance.

1. Install Git

Install Git so you can clone the repository:

sudo apt update
sudo apt install -y git

2. Set up GitHub SSH access

Next, create an SSH key on your instance and add it to your GitHub account. This key lets the instance connect to GitHub; it is separate from the supplied key that lets your laptop connect to the instance. If you haven’t done this before, follow GitHub’s guide.

Generate an SSH key:

ssh-keygen -t ed25519 -C "graviton_cs152"

You can press Enter to accept the default file location. If a key already exists at that location, do not overwrite it: reuse it if appropriate, or choose a different filename when prompted. Remember the path you use.

Print the public key. If you used the default location, run:

cat ~/.ssh/id_ed25519.pub

If you used another filename, replace ~/.ssh/id_ed25519.pub with that key’s public-key path (the filename you chose with .pub appended). Copy the public key only; keep the private key secret.

Copy the output and add it to your GitHub account under Settings → SSH and GPG keys → New SSH key as an Authentication Key.

3. Clone the repository

On the instance, clone your student repository using its SSH URL, which starts with [email protected]:. Replace the placeholders with your student repository’s SSH URL and directory name:

git clone {STUDENT REPO SSH URL}

Navigate into the cloned repository:

cd {STUDENT REPO DIRECTORY}

4. Run the instance setup script

From the cloned repository root on the instance, run:

bash scripts/setup.sh

The script uses sudo to install the compiler and build tools, Python 3 with YAML support, Linux perf, and APerf. It also enables performance counters and profiling, then checks the installed tools. Wait for it to print Setup is complete before continuing.

If setup fails, inspect the installation log, resolve the reported error, and rerun the script:

sudo tail -n 80 /var/log/lab_setup.log

5. Build and test

pgm2svg reads a PGM grayscale image and writes an SVG line drawing, which you can view in a browser. Run the following commands from the repository root:

make benchmark
mkdir -p output
./experiments/001/bin/pgm2svg examples/valve.pgm output/valve

The benchmark builds and tests a saved copy of the code. If you have already run it, replace 001 with the successful experiment number you want to view. Do not delete experiments/; it contains your saved source, binaries, inputs, and results. Git ignores this folder, so pushing your code does not back it up. Open output/valve.svg and check that the program produced a line drawing. You can use VS Code Remote SSH, or copy the SVG to your laptop with scp and open it locally.

Editing the Code

Keep your working copy on the instance. You can edit it with VS Code Remote SSH or an editor in your SSH session. Run build and benchmark commands from that repository’s root on the instance.

Next Step

Once the drawing opens and make benchmark passes, begin the directed portion.