snapshots-app

README

Requirements

• NodeJS v22
• Ruby v3.3.0

We recommend installing the above using nvm and rvm, respectively, to manage your virtual environment. Run all commands in the current directory.

1. Install NodeJS for your OS using nvm with npm (use the dropdowns to generate the correct terminal commands and then run them)
2. Tell nvm you want to use that version now:

nvm use 22

3. Install rvm:

curl -sSL https://get.rvm.io | bash -s stable

4. Install Ruby v3.3.0:

rvm install 3.3.0

Warning

If the command above results in some kind of error related to OpenSSL, you can try running the steps under Troubleshooting to fix your installation.

5. Tell rvm you want to use that version now:

rvm use 3.3.0

Troubleshooting

If you are on MacOS and have OpenSSL installed via Homebrew and are running into an error related to those things when running step 3 above, it is likely because of this issue. Try these commands to fix it:

1. Reinstall OpenSSL v3

brew install openssl@3

2. Clear rvm's cache

rvm cleanup

3. Install Ruby v3.3.0 with the path to the OpenSSL v3 installation:

rvm install ruby-3.3.0 --with-openssl-dir="$(brew --prefix openssl@3)"

Installation

1. Install frontend dependencies:

npm install

2. Install backend dependencies:

bundle install

1. Install overmind which is needed to run the Usage scripts (this assumes you are on MacOS and have already installed Homebrew):

brew install overmind

Usage

To preview the web app locally, run either of the following commands (we recommend the first when developing):

./bin/dev # For HMR (hot module reloading)
# or
./bin/dev static # Without HMR, statically creating the bundles

Visit http://localhost:3000 and see your React On Rails app running on your local development server!

To quit the server press Ctrl + C. You may need to do this twice (not sure why).

Warning

If you ran the server, quit it, ran it again, and then you get this error message:

overmind: It looks like Overmind is already running. If it's not, remove ./.overmind.sock and try again.`

The fix is to do what it says and remove the .overmind.sock file, e.g. run this in your terminal:

rm .overmind.sock

Alternatively, see this comment for a workaround. See also assignment-snapshots#67.

Common Development Commands

# Run unit tests
rake

# Run brakeman (scan for common Rails vulnerabilities)
brakeman

# Run Ruby linter and autocorrect violations
rubocop --autocorrect

# Run Prettier (formats HTML/CSS/JS files in the client directory) and autocorrect violations
npx prettier client/ --write

For more information on these tools, see their documentation:

• Rake
• Brakeman
• Rubocop
• Prettier

Directory Structure

This is a React on Rails app. The Rails part (backend) is under the app/ directory and the React frontend is under the client/ directory.

AWS S3 Configuration and Authentication

S3 is used to store assignment snapshot files. To access S3, you will need to:

1. Request PowerUserAccess through UC Berkeley's managed AWS instance. (You should contact Lisa Yan and Michael Ball to get added properly since you will need access to the correct S3 buckets. See also: internal onboarding docs.)
2. Install the AWS CLI.
3. For local development, configure logging in with SSO with these configuration values and use the AWSPowerUserAccess role:

$ aws configure sso
SSO session name (Recommended): default
SSO start URL [None]: https://ucberkeley.awsapps.com/start/#
SSO region [None]: us-west-2
SSO registration scopes [sso:account:access]: sso:account:access
...
Default client Region [us-west-2]: us-west-2
CLI default output format (json if not specified) [None]: json
Profile name [AWSPowerUserAccess-<omitted>]: default

4. Double check your config, it should look similar to this:

$ cat ~/.aws/config
[default]
login_session = <omitted>
region = us-west-2
sso_session = default
sso_account_id = <omitted>
sso_role_name = AWSPowerUserAccess
output = json
[sso-session default]
sso_start_url = https://ucberkeley.awsapps.com/start/#
sso_region = us-west-2
sso_registration_scopes = sso:account:access

5. Run aws sts get-caller-identity and verify that the currently logged in user is the one you just configured. If it is not, you will need to modify your AWS configuration (for example, by deleting existing profiles from your ~/.aws/config file and deleting unnecessary credentials from your ~/.aws/credentials file, if it exists).
6. Login using the terminal command aws sso login. It should prompt you to login through your browser using your CalNet ID.