Skip to main content

MacBook Pro Setup

This guide takes you from a brand-new MacBook to a working Intealth development machine. Work through it top to bottom — later steps depend on earlier ones.

Before your start date​

On your start date​

Do not work ahead

We perform these steps together as a team. Do not perform steps out of order or on your own.

Wait until you're on a Teams call with the Connected Apps team before starting. Message Seven Thomas (or Patrick Gidich if unavailable) on Teams when you're ready.

General notes​

  • Be patient. Some parts are tedious, but a consistent setup across the team saves everyone time later.
  • You'll receive your username and temporary password on your start date.

Who to contact​

If you run into issues, contact Seven or Patrick first. They may direct you to the Help Desk.

ContactPhoneEmail
Seven Thomas980-259-3376sthomas@ecfmg.org
Patrick Gidich484-431-4487pgidich@intealth.org
Intealth Help Desk215-823-2163servicedesk@intealth.org

Register for password reset​

Do this from your personal laptop (or a private/incognito browser window).

  1. Open Register to Reset Password (Microsoft Support).
  2. Sign in. Your username is your full email address, e.g. jdoe@intealth.org.
  3. Add Phone as a secondary verification method (recommended).
tip

If you ever need to reset your password later, go to passwordreset.microsoftonline.com.

Password requirements​

warning

Passwords cannot be changed more than once in a single day, and must be changed every 6 months.

  • At least 12 characters, containing letters and numbers
  • Cannot contain * or start with a number
  • No common words, known-breached passwords, or variations of "password"
Rule❌ Not acceptable✅ Acceptable
Must differ in characters and words from previous passwordsOld Password123 → New Password12345Old OrionStar → New LemonTrain
No character sequences or repetitionsPassword12345, PasswordAAAA$n0wC@ctu$
No words related to the Enterprise or to you personallyECFMGstarEmployee, FredWilmaPebbles979902, 123MainSt, SpotTheDog, PhillyPhanatic13CabinFishFood
No common passwordsp@ssword, password123—

Step 1 · Start up and sign in​

1.1 Initial macOS setup​

  1. Plug the MacBook into power.

  2. Start up the MacBook and choose the following:

    ScreenChoice
    LanguageEnglish
    RegionUnited States
    Transfer Your Data to This MacSet up as new
    AccessibilityNot Now
    Wi-FiYour Wi-Fi network
    Data & PrivacyContinue

  3. Create your computer account:

    • Full Name: first + last name
    • Account Name: first name (this becomes your username)
    • Password: generate one with 1Password

  4. Sign in with your personal Apple ID, enter the verification code, and accept the Terms & Conditions.

  5. You may be shown the following screens:

    • iCloud Keychain — choose Set Up Later
    • Make This Your New Mac (if shown) — click Continue, then:
      • FileVault Disk Encryption: keep Turn on FileVault checked
      • Allow my iCloud account to unlock my disk: keep checked, then click Continue
      • Touch ID: set it up now
      • Apple Pay: continue without setting up
    • Choose Your Look — light or dark, your choice

1.2 Install software updates​

  1. Press ⌘ + Space, type System Settings, and press Return.
  2. Go to General → Software Update and click Update Now.

1.3 Add your Apple ID (if you skipped it)​

If you skipped Apple ID sign-in earlier, open System Settings and choose Sign in with Apple ID using your personal Apple ID.

Step 2 · Partition drive and create folders​

Your code lives on a dedicated volume named files.

2.1 Create the volume​

  1. Press ⌘ + Space, type Disk Utility, and press Return.
  2. Click + in the toolbar to add a new volume:
    • Name: files
    • Format: APFS

2.2 Create the base folder structure​

  1. Open Finder, press ⌘ + Shift + G, type /Volumes/files, and press Return.

  2. Press ⌘ + Shift + N to create each folder:

    /Volumes/files
    /Volumes/files
    ├── applications   # where you'd install MuleSoft
    ├── cloud-files    # where you'll mount OneDrive
    ├── src            # where your code goes
    └── vm-images      # where Parallels VMs would go

  3. Drag the src folder into Favorites in the Finder sidebar.

  4. In the menu bar, go to Finder → Settings → Sidebar and make sure Hard Disks is checked under Locations.

Step 3 · Install Chrome, 1Password, Office, and Teams​

3.1 Google Chrome​

In Safari, go to google.com/chrome and install Chrome.

note

Safari is a good browser on a Mac, but Chrome's DevTools are excellent for development. Edge is also worth a try.

3.2 Password manager​

If you use 1Password, have your master key ready.

3.3 Microsoft Office​

  1. Sign in at portal.office.com/account with your Intealth/ECFMG credentials and install Office.
  2. When prompted, choose to install for all users.
  3. When prompted to mount OneDrive, mount it to /Volumes/files/cloud-files.
  4. Configure Outlook (⌘ + , opens Settings):

    • Turn off Focused Inbox — uncheck the items shown below:

      Outlook Focused Inbox Settings

    • (Optional) Set Density to Compact under General.

    • Set your working hours to match your normal schedule (7 hours + 1 hour lunch):

      Calendar Work Schedule

3.4 Microsoft Teams​

Skip this if Teams was installed with Office. Otherwise, download it from microsoft.com/microsoft-teams/download-app.

Troubleshooting: Teams install went sideways

Only do this if the normal install fails.

Terminal
sudo pkgutil --forget com.microsoft.teams
rm -r ~/Library/Application\ Support/Microsoft/Teams

Then install the daily build of Teams (raw.githubusercontent.com/ltzLevvie/MicrosoftTeams-msinternal/master/defconfig) and reinstall Teams.

3.5 Say hello​

Post your GitHub handle in the CXA Team group chat in Teams.

Step 4 · Git, runtimes, and Java​

4.1 Apple Command Line Tools (installs Git)​

  1. Open Terminal (⌘ + Space → Terminal) and run the command below. This takes a while.

    Terminal
    xcode-select --install

  2. When prompted, install the command line tools.

  3. Check for and install any updates:

    Terminal
    softwareupdate --list
    softwareupdate --install --all

  4. Open System Settings → Software Update and confirm the command line tools are up to date.

4.2 GitHub SSH keys​

Follow GitHub's guide very carefully: Generating a new SSH key and adding it to the ssh-agent. Your macOS version is newer than 10.12.

  • Do add a passphrase when generating the key.
  • Do not follow the "Generating a new SSH key for a hardware security key" section.
Azure DevOps + GitHub (skip unless directed)
  1. Follow the GitHub instructions above.
  2. Add a second SSH key using the RSA method and add it to your keychain (don't use the .pub extension).
  3. Edit your SSH config using hostname github.com for GitHub and, if instructed, dev.azure.com for Azure DevOps (leave off the .pub extension).
  4. Use pbcopy to copy the .pub key and paste it into your Azure credentials. Azure doesn't support the newer SSH key type that GitHub requires.

Add and verify your @intealth.org email at github.com/settings/emails.

info

You can add your corporate email to your personal GitHub account — it becomes a blended account.

4.4 Configure your Git identity​

Replace the name and email with your own. The email must be a verified email on your GitHub account (personal or @intealth.org).

Terminal
git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

4.5 Homebrew and mise​

  1. Install Homebrew. It will ask for your machine password.

    Don't skip the final step

    When Homebrew finishes, it prints 3 commands to copy and paste into Terminal. Run them, or brew won't be on your PATH.

  2. Open a new Terminal window and install mise:

    Terminal
    brew update && brew install mise

  3. Activate mise in your shell:

    Terminal
    touch ~/.zshrc
    echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
    source ~/.zshrc
Troubleshooting

If mise reports that it doesn't have permission, run mise trust.

Fallback: install Node with NVM (skip unless mise has issues)

  1. In Terminal, make sure your shell profile exists:

    Terminal
    touch ~/.zshrc

  2. Run the install script from nvm-sh/nvm.

  3. Quit and restart Terminal.

  4. Install the latest Node version supported by Azure Functions:

    Terminal
    nvm install v22

4.6 .NET Runtime (macOS ARM64)​

  1. Go to dotnet.microsoft.com/download/dotnet and pick the version marked (latest) / Long Term Support.

  2. Under .NET Runtime, choose macOS → Arm64 → Installer.

  3. Run the installer, then reboot.

  4. Confirm the install in a new Terminal window:

    Terminal
    dotnet --list-runtimes

4.7 Java (Temurin JRE)​

  1. Go to adoptium.net/temurin/releases — Adoptium is the free, open-source Java distribution.

  2. Select:

    OptionValue
    Operating SystemmacOS
    Architectureaarch64
    Package TypeJRE (runtime only — you don't need the JDK)
    VersionLeave the default

  3. Download the .pkg (about 56 MB), run it, then reboot.

  4. Confirm the install:

    Terminal
    java --version

Step 5 · VS Code and Azure tools​

5.1 Azure Functions Core Tools v4​

Terminal
brew tap azure/functions
brew install azure-functions-core-tools@4

5.2 Visual Studio Code​

Download VS Code from code.visualstudio.com/download.

warning

Choose Apple Silicon (zip), not Intel. Unzip it and move the app into Applications.

5.3 Azure CLI​

Terminal
brew update && brew install azure-cli

5.4 Launch VS Code​

Open VS Code to confirm it runs, then continue to the next step.

Step 6 · VS Code extensions​

Install each extension below.

#ExtensionNotes
1GitHub Copilot ChatUsually preinstalled
2GitHub Pull Requests
3Azure Tools
4SonarQube for IDETrust the publisher, then configure it
5Apollo GraphQL
6Azurite
7GitLens
8Vitest Explorer
9SourceryLog in with GitHub
10Python

6.1 Configure SonarQube​

  1. Add the organization key in SonarQube Cloud settings for organization ECFMG:

    SonarQube ECFMG Settings

    ECFMG Key Selection

  2. Add the organization key in SonarQube Cloud for organization Simnova, LLC:

    SonarQube Simnova Settings

    Simnova Key Selection

  3. Confirm the configuration:

    Confirm Configuration

6.2 Arrange the sidebars​

  1. Right-click the vertical activity bar and select Move Primary Side Bar Right.
  2. Right-click Sourcery in the activity bar, select Move to Secondary Side Bar, and log in with GitHub.

Step 7 · Maximize screen resolution​

Go to System Settings → Displays → Advanced, enable Show resolutions as list, and pick the highest resolution you can read comfortably.

tip

More code on screen at once means less scrolling and higher productivity.

Step 8 · Install the VPN​

Optional

Only do this step if you're directed to.

  1. Make sure OneDrive has finished syncing.

  2. Copy the installer to your Desktop: Download AnyConnect VPN

  3. Run the AnyConnect.pkg installer.

    danger

    Do not select any modules other than VPN.

  4. Connect using IntealthOkta:

    • Username: <your username>@ecfmg.org
    • Password: your password
    • Approve the Okta Verify push

  5. Enable the AnyConnect VPN Service under System Settings → General → Login Items:

    Allow Cisco AnyConnect

When to use the VPN

Only connect to submit a timesheet or access the ticketing system. Close other network-heavy apps (e.g. Spotify) while connected, and disconnect as soon as you're done.

Troubleshooting: VPN install went sideways
Terminal
sudo pkgutil --forget com.cisco.pkg.anyconnect.vpn

Then put the installer into a disk image — see here for how.

Step 9 · Rename your MacBook​

Only for Intealth-provided Macs

Skip this step unless Intealth provided a brand-new MacBook Pro.

  1. Open About This Mac:

    About This Mac

  2. Click More Info:

    More Info

  3. Select the name and change it to HQ-MAC-<serial number>:

    Mac Update Name

Step 10 · Enroll your Mac in Intune​

Follow the Intune enrollment documentation.

You're done 🎉

Your MacBook is set up and ready for development.