Developer Environment Setup

Portfolio note: This is an anonymized version of developer onboarding documentation I wrote for a SaaS platform. Company names, hostnames, credentials, and internal paths have been replaced with placeholders.

In this guide: Required Software · Software Installation & Configuration with Homebrew · Creating a SSH key · Clone Codebase · Run & Test Application · Troubleshooting · Optional Configuration · Next Steps

Required Software

• Xcode Command Line Tools
• Homebrew
• Git
• nvm and NodeJS (version 16 — the version the project currently requires)
• AWS CLI
• Chromedriver
• Docker Desktop
• Java JDK (Latest Stable)
• Code Editor
• Postico

Software Installation & Configuration with Homebrew

This document covers installing some of the required software using Homebrew. If you prefer to install using a different method, such as from packages or directly from source, feel free to do so.

Install Xcode command-line tools

Homebrew and Git depend on the Xcode command-line tools, so install them first. Check whether they’re already installed:

xcode-select -p

If this prints a path (for example /Library/Developer/CommandLineTools), skip ahead. Otherwise, install them:

xcode-select --install

A system dialog opens. Click Install and wait for it to finish before continuing.

Install Homebrew

In a new terminal window type the following:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

When the installer finishes, it prints a Next steps section. Run the commands it shows to add Homebrew to your PATH, then confirm it works:

brew --version

Install Git

brew install git

Install nvm

nvm (Node Version Manager) lets you install and switch between Node versions per project.

brew install nvm
mkdir ~/.nvm

Update your shell to find nvm

Since macOS Catalina, the default shell is zsh; older systems may still use bash. Determine which shell you are running and edit the appropriate startup file.

echo $SHELL
/bin/zsh   # zsh: need to edit the .zprofile
/bin/bash  # bash: need to edit the .bash_profile

Open a terminal in your home directory, then use a text editor of your choice to edit your startup file.

If you don’t have a startup file, this will create it. Don’t forget that these are system files and start with a dot [.]

cd ~
vi [STARTUP FILE]

Add the following lines (they work on both Apple silicon and Intel Macs):

export NVM_DIR="$HOME/.nvm"
[ -s "$(brew --prefix nvm)/nvm.sh" ] && . "$(brew --prefix nvm)/nvm.sh"  # Loads nvm
[ -s "$(brew --prefix nvm)/etc/bash_completion.d/nvm" ] && . "$(brew --prefix nvm)/etc/bash_completion.d/nvm"  # Loads nvm bash_completion

Save the file, then reload it and confirm nvm is available:

source ~/.zprofile   # or: source ~/.bash_profile
nvm --version

Install NodeJS (version 16)

nvm install 16
nvm use 16
node --version   # should print v16.x.x

If the repository contains an .nvmrc file, run nvm use from the project folder and nvm will pick the correct version automatically.

Install the AWS command line tools

brew install awscli

Install Chromedriver

brew install chromedriver

Install Docker Desktop

brew install --cask docker

The --cask flag installs the Docker Desktop app. Without it, Homebrew installs only the command-line client, which can’t run containers on its own.

Launch Docker from the Applications folder — you do not need to log in, but it must be running.

On first launch it will ask for permission — enter your computer password and continue.

If you have docker errors, be sure that the application is running. You may also need to log in to your docker account at least once.

Install Java JDK

Install the latest stable JDK, either from Oracle or with Homebrew:

brew install --cask temurin
java -version

Install Code Editor

Install a code editor such as VS Code:

brew install --cask visual-studio-code

Install Interface for Postgres

Sometimes you will need to directly modify the database. A GUI such as Postico makes this easier:

brew install --cask postico

localhost database — the following information is the default local db (when developing locally):

• HOST: localhost
• USERNAME: <local-dev-user>
• PASSWORD: <local-dev-password>
• DATABASE: cloud (this is only there once the api has been started)

Creating a SSH key

You will need a SSH key in order to access GitLab. Ensure that Git has been successfully installed, then do the following:

1. In a new terminal type the following:

ssh-keygen -t ed25519 -C "<your_name>@example.com"

2. Next, you will be prompted to input a file path to save your SSH key pair to.

If you don’t already have an SSH key pair and aren’t generating a deploy key, use the suggested path by pressing Enter. Using the suggested path will normally allow your SSH client to automatically use the SSH key pair with no additional configuration.

3. Once the path is decided, you will be prompted to input a password to secure your new SSH key pair. It’s a best practice to use a password, but it’s not required and you can skip creating it by pressing Enter twice.

Expected Output

Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/yourname/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/yourname/.ssh/id_ed25519.
Your public key has been saved in /Users/yourname/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:s###########################Q yourname@example.com
The key's randomart image is:

If you already have an SSH key pair with the suggested file name, you have two options: 1. Overwrite or 2. Choose a new name.

Option 1 — Overwrite: If you do not need the old key, you can choose to overwrite it (this is the simplest and most common option).

$ ssh-keygen -t ed25519 -C "<your_name>@example.com"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/yourname/.ssh/id_ed25519):
/Users/yourname/.ssh/id_ed25519 already exists.
Overwrite (y/n)? y
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/yourname/.ssh/id_ed25519.
Your public key has been saved in /Users/yourname/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:s###########################Q yourname@example.com
The key's randomart image is:

Option 2 — New Name: If you need to keep the existing ed25519 key, you will need to input a new file name.

$ ssh-keygen -t ed25519 -C "<your_name>@example.com"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/yourname/.ssh/id_ed25519):
/Users/yourname/.ssh/id_ed25519 already exists.
Overwrite (y/n)? n
$ ssh-keygen -t ed25519 -C "<your_name>@example.com"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/yourname/.ssh/id_ed25519): /Users/yourname/.ssh/id_ed25519_alt
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/yourname/.ssh/id_ed25519_alt.
Your public key has been saved in /Users/yourname/.ssh/id_ed25519_alt.pub.
The key fingerprint is:
SHA256:s###########################Q yourname@example.com
The key's randomart image is:

Accessing your GitLab account via SSH

Login to https://git.example.com/. This is our private Gitlab instance where all of our projects are hosted. The core project you will be working on is “studio.” If you haven’t been given a login for gitlab yet, ask the engineering manager for access.

1. In your terminal, copy your public SSH key to the clipboard:

pbcopy < ~/.ssh/id_ed25519.pub

If you renamed the key from id_ed25519 to a custom name you should enter the custom name in the above step.

2. Add your public SSH key to your GitLab account:
   • Navigate to https://git.example.com/
   • Click on your avatar in the upper right corner and select Settings.
   • Navigate to SSH Keys and paste your public key in the “Key” section.
   • If you created the key with a comment, this will appear under “Title”. If not, give your key an identifiable title, i.e. “Work Laptop” or “Home Workstation”.
   • Click Add key.
3. To check that everything is set up correctly, in your terminal type:

ssh -T -i ~/.ssh/id_ed25519 git@git.example.com

Expected Result

Welcome to GitLab, @username!

The first time you connect to GitLab via SSH, you will be asked to verify the authenticity of the GitLab host you are connecting to. Answer yes to add the host to your list of trusted hosts. Once added to the list of known hosts, you won’t be asked to validate the authenticity of GitLab’s host again. Run the above command once more, and you should only receive a successful login reply.

The authenticity of host 'git.example.com (x.x.x.x)' can't be established.
ED25519 key fingerprint is SHA256:<host-key-fingerprint>.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'git.example.com' (ED25519) to the list of known hosts.

Clone Codebase

1. Choose a directory to store your development environment. This guide uses ~/dev.
2. Create the directory and move into it:

mkdir -p ~/dev && cd ~/dev

3. Clone the project:

git clone git@git.example.com:org/studio

Run & Test Application

Now that your environment is set up and your codebase is configured, the following steps will allow you to launch the application based on various scenarios. This will also verify that your system is configured correctly.

Run Studio for Web

1. Navigate to the studio directory, switch to the project’s Node version, and install node packages:

cd ~/dev/studio
nvm use 16
npm install

2. Navigate to the studio/api directory and install node packages:

cd api
npm install

3. Navigate to the studio/appserver directory and install node packages:

cd ../appserver
npm install

4. Verify your Docker App is running.

If you’re running pgsql, redis and minio or other s3 clones locally, you should stop them before continuing.

5. Return to the project root and start your local resources (Postgres, Redis, and MinIO for S3 emulation). This runs docker-local-dev-env-up.sh:

cd ~/dev/studio
npm run localdevenv:up

You should see the following output:

> studio@0.4.0 localdevenv:up /Users/<your username>/dev/studio

d4e2da59c4c72643326006ac58151e91d609a7bf5c4053376760ee0e83d804f5
3910aa8a6b2e28f25ad61f4b8538292bbe5acfecdcf78541791b31396bf1803d
75f83c39dfed0ce7970e1d196f7c698fb3b2183ab9cb4c90a5d24c4d0357738a
Creating Studio bucket on Minio storage
make_bucket: studio
Created Studio bucket on Minio storage

6. This also creates a local file with all the necessary environment variables that the components need, called .env_local_dev (studio/.env_local_dev):

ls -a | grep .env_local_dev
.env_local_dev

You will need to add the OAuth (Auth0) settings to studio/.env_local_dev:

# studio/.env_local_dev
export CROSS_ORIGIN=*
export OAUTH_TENANT=your-tenant.auth0.com
export OAUTH_CLIENT_ID=<YOUR_CLIENT_ID>
export OAUTH_CLIENT_SECRET=<GET FROM PASSWORD MANAGER>

7. Open a new terminal and run the api locally:

cd ~/dev/studio/api
npm run start:local

This should play the migration script on the empty local db and start up the api.

8. Open a second new terminal and run the appserver locally:

cd ~/dev/studio/appserver
npm run start:local

9. Open a third terminal at the project root, upload the scaffold, and launch the local browser instance:

cd ~/dev/studio
npm run upload-scaffold:local
npm run dev:web

You should now have three terminals running: the api, the appserver, and the web client. If the browser opens and loads Studio, your environment is set up correctly.

Troubleshooting

Optional Configuration

Linting with VSCode

The following steps will automatically apply the correct code formatting on File Save. This is optional, so feel free to skip this part.

1. Install the ESLint extension in VS Code.
2. In the project’s .vscode directory, create a file named settings.json with the following content:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"]
}

3. Quit and restart VS Code.
4. Now you should be able to test for “on save correction” for team code style violations such as:
   • single quotation marks instead of double
   • extra spaces after statements
   • declared but unused variables
   • fix indentation (manually triggered)
   • experimental: decorator linting (needed for MobX)

Project-level settings in .vscode/settings.json apply only to this repository, so they won’t change how VS Code formats your other projects.

Next Steps

• Pulling Assets (Prefabs) for Asset Bar: https://git.example.com/org/studio/-/wikis/Local-Prefabricator-Asset-Bar-Guide
• Read Our Process
• Read Our Wiki