Developer Environment Setup#

Version: 1.0 Last Updated: 2026-04-03 Applies To: All RFS Services developers setting up a new workstation

Overview#

This document walks you through setting up a complete development environment for RFS Services projects. It covers three paths:

Windows users — Install WSL (Windows Subsystem for Linux), then set up Ubuntu inside it.
macOS users — Skip directly to Part 2.
Native Linux (Ubuntu) users — Skip directly to Part 3.

Windows and Linux paths converge at the same Ubuntu setup steps. macOS follows a parallel path using Homebrew. A final optional section covers connecting Zed and VS Code to your WSL instance remotely (Windows only).

Part 1 — Install WSL (Windows Only)#

Skip this section if you are running Ubuntu natively.

1.1 Enable WSL#

Open PowerShell as Administrator and run:

wsl --install

This installs WSL 2 and Ubuntu (the default distribution) in a single step. When prompted, restart your machine.

If you already have WSL installed but Ubuntu is not your default distro, run:
wsl --install -d Ubuntu

1.2 Complete the Ubuntu First-Run Setup#

After restarting, Ubuntu will open automatically and finish installing. You will be prompted to:

Create a UNIX username (lowercase, no spaces — this does not need to match your Windows username).
Create and confirm a UNIX password.

Once complete, you will be dropped into a Bash shell inside your Ubuntu environment. All subsequent steps in this document are run inside this shell unless otherwise noted.

1.3 Launch WSL and Set Up Windows Terminal#

Windows Terminal is the recommended way to access WSL. It supports multiple tabs, profiles, and customization, and it integrates with WSL automatically.

Install Windows Terminal (if not already installed):

Open PowerShell and run:

winget install --id Microsoft.WindowsTerminal -e

Alternatively, install it from the Microsoft Store.

Set Ubuntu as the default profile:

Open Windows Terminal.
Click the dropdown arrow (∨) next to the new tab button and select Settings (or press Ctrl+,).
Under Startup, set the Default profile to Ubuntu.
Click Save.

From now on, opening Windows Terminal will drop you directly into your Ubuntu/WSL shell.

Useful shortcuts in Windows Terminal:

Action	Shortcut
New tab (default profile)	`Ctrl+Shift+T`
New Ubuntu tab specifically	`Ctrl+Shift+[Ubuntu profile number]`
Switch between tabs	`Ctrl+Tab` / `Ctrl+Shift+Tab`
Split pane horizontally	`Alt+Shift+−`
Split pane vertically	`Alt+Shift++`

Launching WSL from elsewhere:

If you ever need to open WSL without Windows Terminal, you can still run wsl from any PowerShell or Command Prompt window, or open Ubuntu directly from the Start menu.

Part 2 — macOS Dev Environment Setup#

Skip this section if you are on Windows or Linux. macOS is Unix-based, so no virtual machine or compatibility layer is needed. Run all commands from the Terminal app by typing or pasting them into the console and pressing enter.

2.1 Install Xcode Command Line Tools#

Git and other developer utilities on macOS require Xcode Command Line Tools. If you haven't installed them yet, run:

xcode-select --install

A dialog will appear prompting you to install. Click Install and wait for it to complete (~5 minutes). You can verify afterwards with:

git --version

2.2 Install Homebrew#

Homebrew is the standard package manager for macOS. If it is not already installed:

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

Follow any on-screen prompts (you may need to enter your password). After installation, follow any instructions printed at the end about adding Homebrew to your PATH. It typically looks like:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify:

brew --version

2.3 Update Homebrew and Upgrade Packages#

brew update && brew upgrade

2.4 Install Firefox ESR#

You can install Firefox ESR directly via Homebrew Cask:

brew install --cask firefox@esr

Verify by opening Firefox ESR from your Applications folder, or run:

open -a "Firefox ESR"

2.5 Create an SSH Key#

Generate a new ED25519 SSH key pair. When prompted, enter a descriptive filename rather than accepting the default. This will be your Github SSH key.

ssh-keygen -t ed25519 -C "your.email@revolutionfield.com"

At the prompt:

Enter file in which to save the key (/Users/<you>/.ssh/id_ed25519):

Type a custom path, for example:

/Users/<you>/.ssh/rfs_github_ed25519

You will then be asked for an optional passphrase. Using a passphrase is recommended; press Enter twice to skip.

Start the SSH agent and add your new key:

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/rfs_github_ed25519

The --apple-use-keychain flag saves the passphrase to your macOS Keychain so you won't be prompted for it on every login.

Ensure the key is loaded automatically on login by running the following command (copy the whole code block and paste it in as one line). It will add a section to ~/.ssh/config (creating the file if it doesn't exist):

mkdir -p ~/.ssh && chmod 700 ~/.ssh
cat >> ~/.ssh/config << 'EOF'
Host github.com
  IdentityFile ~/.ssh/rfs_github_ed25519
  AddKeysToAgent yes
  UseKeychain yes
EOF
chmod 600 ~/.ssh/config

2.6 Register the SSH Key with GitHub#

Copy your public key to the clipboard (if you used a different name for the ssh key use that here with the .pub extension):

pbcopy < ~/.ssh/rfs_github_ed25519.pub

Then in your browser:

Go to GitHub → Settings → SSH and GPG keys (https://github.com/settings/keys).
Click New SSH key.
Give it a descriptive title (e.g. RFS Dev — MacBook Pro).
Paste your public key into the Key field.
Click Add SSH key.

Verify the connection:

ssh -T git@github.com

You should see:

Hi <your-username>! You've successfully authenticated, but GitHub does not provide shell access.

2.7 Clone the RFS Projects Repository#

cd ~
git clone git@github.com:rev-field/rfs-projects.git

You should see Git cloning the repository into ~/rfs-projects/.

2.8 Install `uv`#

uv is the Python package and project manager used by RFS Services. Install it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Reload your shell so the uv binary is on your PATH:

source $HOME/.local/bin/env

Verify:

uv --version

2.9 Sync the Project Dependencies#

cd ~/rfs-projects
uv sync

uv will create a .venv directory inside the project and install everything specified in pyproject.toml / uv.lock.

2.10 Create the `.env` Directory#

mkdir -p ~/rfs-projects/.env

This folder is listed in .gitignore and will never be committed to the repository. Keep all secrets, credentials, and environment files inside it.

2.11 Copy Configuration Files into `.env`#

You will be provided with any secrets files required for your projects, contact your supervisor if unsure whether you have what you need. Unzip the provided folder if necessary, and copy the configuration directory from your download location (e.g. your Downloads folder) into the .env folder you created:

cp -r ~/Downloads/[config-directory]/ ~/rfs-projects/.env/

Replace [config-directory] with the actual folder you downloaded.

Part 3 — Ubuntu Dev Environment Setup#

Skip this section if you are on macOS. Run all commands inside your Ubuntu/Linux terminal (or WSL shell on Windows).

3.1 Add the Mozilla PPA#

Ubuntu's default repositories ship Firefox as a Snap package, which will not work with our browser automations. To install a traditional .deb version instead, add the Mozilla Team PPA and configure APT to prefer it.

Add the PPA:

sudo add-apt-repository ppa:mozillateam/ppa

Pin the PPA so it takes priority over the Snap:

echo '
Package: firefox*
Pin: release o=LP-PPA-mozillateam
Pin-Priority: 1001
' | sudo tee /etc/apt/preferences.d/mozilla-firefox

Prevent Ubuntu from re-installing the Snap version automatically:

echo 'Unattended-Upgrade::Allowed-Origins:: "LP-PPA-mozillateam:${distro_codename}";' \
  | sudo tee /etc/apt/apt.conf.d/51unattended-upgrades-firefox

3.2 Update and Upgrade Packages#

Refresh your package lists and apply all available upgrades:

sudo apt update && sudo apt upgrade -y

This may take a few minutes on a fresh install.

3.3 Install Firefox ESR#

sudo apt install firefox-esr -y

Verify the installation:

firefox-esr --version

WSL note: Firefox ESR requires a display server to launch a GUI window. This works automatically on Windows 11 via WSLg. On Windows 10 you will need a third-party X server (e.g. VcXsrv) configured if you want to use non-headless firefox for debugging.

3.4 Create an SSH Key#

Generate a new ED25519 SSH key pair. When prompted, enter a descriptive filename rather than accepting the default — use a name that identifies this machine and/or its purpose.

ssh-keygen -t ed25519 -C "your.email@revolutionfield.com"

At the prompt:

Enter file in which to save the key (/home/<you>/.ssh/id_ed25519):

Type a custom path, for example:

/home/<you>/.ssh/rfs_github_ed25519

You will then be asked for an optional passphrase. Using a passphrase is recommended for security; press Enter twice to skip.

Start the SSH agent and add your new key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/rfs_github_ed25519

3.5 Register the SSH Key with GitHub#

Copy your public key to the clipboard:

cat ~/.ssh/rfs_github_ed25519.pub

Select and copy the entire output (it begins with ssh-ed25519).

Then in your browser:

Go to GitHub → Settings → SSH and GPG keys (https://github.com/settings/keys).
Click New SSH key.
Give it a descriptive title (e.g. RFS Dev — WSL Ubuntu).
Paste your public key into the Key field.
Click Add SSH key.

Verify the connection:

ssh -T git@github.com -i ~/.ssh/rfs_github_ed25519

You should see:

Hi <your-username>! You've successfully authenticated, but GitHub does not provide shell access.

If you used a custom key filename, ensure your ~/.ssh/config maps it to github.com so Git picks it up automatically:
cat >> ~/.ssh/config << 'EOF'
Host github.com
  IdentityFile ~/.ssh/rfs_github_ed25519
  AddKeysToAgent yes
EOF
chmod 600 ~/.ssh/config

3.6 Clone the RFS Projects Repository#

Navigate to the directory where you want to store the project (your home directory is fine to start):

cd ~

Clone using SSH:

git clone git@github.com:rev-field/rfs-projects.git

You should see Git cloning the repository into ~/rfs-projects/.

3.7 Install `uv`#

uv is the Python package and project manager used by RFS Services. Install it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Reload your shell so the uv binary is on your PATH:

source $HOME/.local/bin/env

Verify:

uv --version

3.8 Sync the Project Dependencies#

Change into the cloned project directory:

cd ~/rfs-projects

Run uv sync to install all project dependencies into a managed virtual environment:

uv sync

uv will create a .venv directory inside the project and install everything specified in pyproject.toml / uv.lock.

32.9 Create the `.env` Directory#

At the root of the project tree, create a .env folder to hold environment-specific configuration files:

mkdir -p ~/rfs-projects/.env

This folder is listed in .gitignore and will never be committed to the repository. Keep all secrets, credentials, and environment files inside it.

3.10 Copy Configuration Files into `.env`#

This step differs depending on your operating system. You will be provided with any secrets files required for your projects, contact your supervisor if unsure whether you have what you need. Unzip the provided folder if necessary, and copy the configuration directory from your download location (e.g. your Downloads folder) into the .env folder you created.

Option A — WSL (Windows)#

Your Windows drives are mounted under /mnt/ inside WSL. Copy the required configuration directory from its Windows location into your new .env folder:

cp -r /mnt/c/path/to/[config-directory]/ ~/rfs-projects/.env/

Replace /mnt/c/path/to/[config-directory] with the actual Windows path to the directory you received. For example, if the folder lives at C:\RFS\config, the WSL path is /mnt/c/RFS/config.

Option B — Native Linux#

Copy the configuration directory from your download location (e.g. your Downloads folder):

cp -r ~/Downloads/[config-directory]/ ~/rfs-projects/.env/

Replace [config-directory] with the actual folder you received.

Part 4 — Connect Your Editor to WSL (Windows Only)#

Skip this section if you are running Ubuntu natively or are on a Mac.

Both Zed and VS Code support working directly inside your WSL environment, giving you Linux tooling with a native Windows UI.

3.1 VS Code — WSL Remote Extension#

Install the extension:

Open VS Code on Windows.
Open the Extensions panel (Ctrl+Shift+X).
Search for WSL and install the extension published by Microsoft (extension ID: ms-vscode-remote.remote-wsl).

Open the project in WSL:

From your WSL terminal, navigate to the project and launch VS Code:

cd ~/rfs-projects
code .

VS Code will open a new window with a green WSL: Ubuntu badge in the bottom-left corner, confirming you are connected to the WSL file system and running extensions inside Linux.

Alternatively, use the Command Palette (Ctrl+Shift+P) → WSL: Open Folder in WSL… to browse to any WSL directory from within VS Code.

Subsequent sessions:

VS Code remembers WSL connections. You can reopen recent WSL folders from File → Open Recent just like any local folder.

3.2 Zed — WSL Remote#

Install from Command Palette

Open Zed on Windows.
Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
Select projects: open remote.
Select Add WSL Distro
Select Ubuntu
You will see a new section appear under that heading now, WSL: Ubuntu
Select Open Folder and type ~/rfs-projects to open a new Zed window with the remote project
This folder will be saved for future use, you can also use File > Open Remote (or File > Open Recent) To access your project

Appendix — Quick Reference#

Windows / Linux (Ubuntu/WSL)

Task	Command
Enter WSL	`wsl` (in PowerShell/CMD)
Update packages	`sudo apt update && sudo apt upgrade -y`
Add SSH key to agent	`ssh-add ~/.ssh/rfs_github_ed25519`
Test GitHub SSH	`ssh -T git@github.com`
Start project env	`cd ~/rfs-projects && uv sync`
Start WSL SSH server	`sudo service ssh start`

macOS

Task	Command
Update Homebrew & packages	`brew update && brew upgrade`
Copy public key to clipboard	`pbcopy < ~/.ssh/rfs_github_ed25519.pub`
Add SSH key to agent (Keychain)	`ssh-add --apple-use-keychain ~/.ssh/rfs_github_ed25519`
Test GitHub SSH	`ssh -T git@github.com`
Start project env	`cd ~/rfs-projects && uv sync`

For questions or issues, contact your supervisor

Developer Environment Setup#

Overview#

Part 1 — Install WSL (Windows Only)#

1.1 Enable WSL#

1.2 Complete the Ubuntu First-Run Setup#

1.3 Launch WSL and Set Up Windows Terminal#

Part 2 — macOS Dev Environment Setup#

2.1 Install Xcode Command Line Tools#

2.2 Install Homebrew#

2.3 Update Homebrew and Upgrade Packages#

2.4 Install Firefox ESR#

2.5 Create an SSH Key#

2.6 Register the SSH Key with GitHub#

2.7 Clone the RFS Projects Repository#

2.8 Install uv#

2.9 Sync the Project Dependencies#

2.10 Create the .env Directory#

2.11 Copy Configuration Files into .env#

Part 3 — Ubuntu Dev Environment Setup#

3.1 Add the Mozilla PPA#

3.2 Update and Upgrade Packages#

3.3 Install Firefox ESR#

3.4 Create an SSH Key#

3.5 Register the SSH Key with GitHub#

3.6 Clone the RFS Projects Repository#

3.7 Install uv#

3.8 Sync the Project Dependencies#

32.9 Create the .env Directory#

3.10 Copy Configuration Files into .env#

Option A — WSL (Windows)#

Option B — Native Linux#

Part 4 — Connect Your Editor to WSL (Windows Only)#

3.1 VS Code — WSL Remote Extension#

3.2 Zed — WSL Remote#

Appendix — Quick Reference#

2.8 Install `uv`#

2.10 Create the `.env` Directory#

2.11 Copy Configuration Files into `.env`#

3.7 Install `uv`#

32.9 Create the `.env` Directory#

3.10 Copy Configuration Files into `.env`#