To get familiar with VS Code it's recommended to read the getting started section of the VS Code docs so you're familiar with the UI terminology.
Opening the FxA repository will result in VS Code prompting you (in the lower right of your VS Code Window) to install the project's "Recommended Extensions". These include all the common extensions that will help in working with the FxA project's packages.
In VS code, you typically open up a folder and the
.vscode directory inside
is used for the project's debugging/task configurations and settings. Since the
FxA repository is a mono-repo containing many individual packages, a single
.vscode in the root directory is used for monorepo-wide settings and
to recommend extensions. However, there are
.vscode directories within the
packages/* that add additional package specific debugging/task
To utilize these you can open the desired package folder directly or use a multi-root workspace. Using the multi-root workspace feature allows you to add multiple package folders to your workspace which enables all of their individual debugging/task configurations.
See the VS Code docs for instructions on how to add a folder to your workspace. Note that the first time you add a folder it will create a new Unnamed Workspace. You can save the workspace as a file to easily resume the chosen open package folders for future use as well.
Using the VS Code Debugger
Once you have added a folder to your workspace, the additional debug/task settings
will be available in the Debug View. If you don't see any after adding
a package folder with a
.vscode directory, you may need to run 'Developer: Reload Window'
from the command palette.
The following videos show how to run test tasks and the FxA Auth Server with the debugger.
Collaborative Coding / Review
The recommended extensions for FxA install the LiveShare Extension Pack which includes the LiveShare extension. Using this extension you can share your editing and debugging environment including local terminals and the debug session with invited developers.
VS Code has documented common use-cases for Live Share that provide useful tips for setting up collaborative coding sessions. A good jumping off point to learn more features available is the LiveShare feature overview.
When working collaboratively, the final commit should reflect all the collaborators that
worked on it. GitHub properly displays commits written with the
line appended to the commit message.
Remote Development via SSH
Remote development allows you to run the VS Code user interface on your local machine while a core VS Code instance is run on a remote machine either via SSH, WSL, docker Containers, or VS Online Azure instances. These instructions are tips for setting up VS Code to work with a remote instance via SSH, and should be run on the remote instance.
Copy your local ssh public key to the remote machine on setup, this will create a user with the username from your ssh keys email address.
It's useful to configure the forwards for FxA in your
~/.ssh/config file so that
they're always active upon loading up VS Code. An example is shown below:
LocalForward 1080 localhost:1080
LocalForward 1111 localhost:1111
LocalForward 1112 localhost:1112
LocalForward 3030 localhost:3030
LocalForward 3031 localhost:3031
LocalForward 8080 localhost:8080
LocalForward 9000 localhost:9000
LocalForward 9010 localhost:9010
LocalForward 9292 localhost:9292
# vnc port
LocalForward 5901 localhost:5901
Increase File watch Limit
Add this line to the end of
Reload sysctl settings:
sudo sysctl -p
Set your email/username:
git config --global user.email "email@example.com"
git config --global user.name "Your Name"
Configure your favorite editor for commit messages (vim):
git config --global core.editor vim
Using SSH/GPG Agent Forwarding
For security reasons it’s useful to avoid leaving SSH/GPG keys on remote development instances.
Enable agent forwarding option:
User Settings -> Search for ‘agent’, verify
Remote.SSH: Enable Agent Forwarding
Ensure you are running a local ssh-agent. You can see whether your agent is running
and has keys added to it by running
ssh-add -l locally. If you do not see your keys,
run ssh-add and it will prompt to add your default keys or view the ssh-add docs to
add specific keys to your agent.
Additional instructions for ensuring your ssh-agent is running.
You will then need to add the appropriate setting to your
~/.ssh/config file used
with VS Code. For the host in your config file, add
ForwardAgent yes, as shown:
Open a VS Code session to the remote host, and in the Terminal window run
to verify the keys from the SSH agent are available. GPG Configuration Based on the
GnuPG Agent Forwarding documentation.
On your local machine get the location of the extra GPG socket:
gpgconf --list-dir agent-extra-socket
Install gnupg on remote server:
sudo apt-get install gnupg
On the remote machine, get the location of the GPG socket:
gpgconf --list-dir agent-socket
On the remote machine, edit the
/etc/ssh/sshd_config file to add:
Restart the remote machine’s sshd service
Ensure that your bash account prompts you for the GPG passphrase correctly by editing
Export your GPG public keys and import them on the remote machine.
Edit the local
~/.ssh/config file used with VS Code to include the GPG agent socket:
RemoteForward /run/user/1000/gnupg/S.gpg-agent /c/Users/USERNAME/AppData/Roaming/gnupg/S.gpg-agent.extra
Note that the remote agent-socket is first, followed by the local agent extra socket. On
Windows systems the
C:\... path should be translated as shown in the above example.
If you use gpg on the remote system already, you may need to delete the gpg-agent
file that already exists.
Using SSH/GPG Keys on the Remote Server
This is a less secure method as the remote server has your ssh/gpg keys that could be compromised. This method should only be used if you are unable to get GPG agent forwarding working, which can occasionally occur between some client and SSH host OS's.
GnuPG (Commit signing)
Most developers have a primary key they regularly use. To prevent this key from possibly leaking it's recommended to generate a new key for the remote machine with a rather long randomly generated password you keep in a password manager.
Install gnupg on remote server
sudo apt-get install gnupg
Create a new gpg key
gpg --default-new-key-algo rsa4096 --gen-key
Enter your name and e-mail address to use.
Set the password from the password manager
Run npm install in a separate window to help generate sufficient randomness on the server
Tell git about your gpg key
Auto-sign commits per project or everywhere
Add your GPG public key to your GitHub account
Ensure that your bash account prompts you for the GPG passphrase correctly by editing your