Development Environment Setup

This guide walks you through installing and configuring the tools you need for local Apothesource development on macOS.

The setup script automates nearly everything on this page. Use this page as the reference for what it does, or to set things up by hand.

Pick one before you start. If you set things up by hand, finish by hand, then run ngss-dev-setup.sh doctor to check your work; the script’s guided setup stops if it finds a setup started by hand.

Browser Bookmarks

See Developer Bookmarks for a set of helpful links that you may import into your browser.

Homebrew

Homebrew is a package manager for installing many of the tools you will need. Install it from brew.sh.

If installation fails, you may need to install the Xcode Command Line Tools first by running xcode-select --install in a terminal, and then re-run the Homebrew installation command.

To download Xcode itself, go to https://developer.apple.com/xcode/ and follow the instructions. You may use your personal Apple ID to sign in to the App Store and download Xcode, or you can create an Apple ID using your Apothesource email address. If you have any issues with the installation, discuss with Onboarding leadership.

git

Install from git-scm.com.

Update your git config with your real name and work email:

git config --global user.name "<NAME>"
git config --global user.email "<NAME>@apothesource.com"

Disable revision times for safer rebasing:

git config --global core.trustctime false

SDKMAN

To make it easier to manage your development environment, install SDKMAN, the Software Development Kit Manager:

curl -s "https://get.sdkman.io" | zsh

Follow the instructions in the terminal output to source your shell configuration after installation.

If you have any issues during installation, consult with the Onboarding team.

Java

Apothesource projects use Java 21 and Java 17. Install both using SDKMAN.

Our current default Java 21 version is Temurin 21.0.10:

sdk install java 21.0.10-tem

Install Java 17 (Temurin 17.0.13) the same way:

sdk install java 17.0.13-tem

You will be prompted whether you want each version to be the default during installation. To see which Java versions are installed and available:

sdk list java

sdk list java only shows the newest build of each Java release, so 21.0.10 and 17.0.13 may not appear in it. sdk install java 21.0.10-tem still works.

The current default version is denoted with >>> next to its version number. To change which version of Java your system uses by default:

sdk default java <identifier>

Alternatively, to change only the version used by your current shell:

sdk use java <identifier>

Enable Auto-Switching of JDK Versions

To allow SDKMAN to auto-switch to a service’s configured JDK (found in the service’s .sdkmanrc file), set the following in ~/.sdkman/etc/config:

sdkman_auto_env=true

For information about other configuration options, see https://sdkman.io/.

Maven

Install Maven 3.9.15 using SDKMAN. That’s the version our services pin in their .sdkmanrc files; a plain sdk install maven installs the newest Maven (3.10 or later), which the services don’t use yet.

sdk install maven 3.9.15

Check your install for any errors:

mvn --version

Since Maven is installed with SDKMAN, the version of Java used by Maven matches the configured default or shell JDK.

Gradle

Install using SDKMAN:

sdk install gradle

The default installed version should work fine, but if you have any issues, use the steps above to list other available versions and set a different default.

Skaffold / Kustomize

Install Skaffold and Kustomize and set up your environment according to the Skaffold and Kustomize Setup documentation.

Optionally, but highly recommended, install the Gemini Code Assist / Cloud Code plugin (formerly Google Cloud Code) for IntelliJ.

Orbstack

Orbstack is our preferred container runtime for development. Install via Homebrew:

brew install orbstack

Review the Orbstack migration guide to configure Orbstack for your environment, or if switching to Orbstack from Docker Desktop.
To obtain an Orbstack license:
1. Log in to Orbstack using your Apothesource email.
2. Contact Jim Leonard or Amy Calvert to have a license assigned.

Make sure to turn on Enable Kubernetes cluster under Settings → Kubernetes.

If you have an Apple Silicon Mac, you may need to disable Rosetta emulation for Orbstack when building certain services. If you run into issues building or running services, try toggling off the Use Rosetta to run Intel code setting under Settings → System.

Docker Desktop

Alternatively, you can use Docker Desktop as your container runtime. Download and install the community edition from Docker.

If you have an Apple Silicon Mac, make sure to enable Apple Virtualization framework under General → Virtual Machine Options, and turn on Use Rosetta for x86/amd64 emulation on Apple Silicon (Docker v4.16.1 and up).

K8s Monitoring Tools

Use Homebrew to install Headlamp, an easy-to-use tool for monitoring your Kubernetes cluster, deployments, pod logs, etc.

brew install --cask headlamp

Follow the instructions for configuration on the K8s Monitoring Tools page. Here you will also find links to other tools that can be used to monitor your local Kubernetes cluster.

IntelliJ

Most developers use IntelliJ as their preferred IDE. Download IntelliJ Ultimate here. You can obtain a license key from Amy Calvert.

With IntelliJ closed, ngss-dev-setup.sh intellij (from the setup script) installs the plugins and imports the code style and inspections described below.

Open a Project

This should be done after you can build a Java service, so make sure to finish the steps in the new hire checklist before proceeding.

After you can successfully build, open IntelliJ and go to File → Open, select location-service/pom.xml, and then select Open as Project.

PlantUML Integration

We use PlantUML and the PlantUML IntelliJ plugin for generating diagrams from .puml files. To set up this integration:

Install PlantUML. From a terminal, run brew install plantuml.
Install the PlantUML4Idea plugin. In IntelliJ, go to Settings → Plugins, search for "PlantUML", and install the PlantUML4Idea plugin.
Configure the plugin. In IntelliJ, go to Settings → Languages and Frameworks → PlantUML. In the Graphviz dot executable field, enter the path that which dot prints (/opt/homebrew/bin/dot on Apple silicon Macs, /usr/local/bin/dot on Intel Macs) and select OK. Restart IntelliJ for this to take effect.

CodeStyle and Inspections

Follow the instructions in IntelliJ Checkstyle & Inspection Profiles to import our shared CodeStyle and Inspections configurations into your IntelliJ environment. This helps ensure consistency across our codebase and saves you time formatting and resolving findings.

Debugger Configuration

See Skaffold Debugging with IntelliJ for tips on debugging Skaffold services and connecting to local databases with IntelliJ.

Postman

Postman is a tool for sending and testing API requests. Download and install it here.

Other Tools

A list of other useful development tools can be found here.

Adjust Settings

Add Credentials to Container Registry

Run the steps below in the terminal to add your credentials using the OSX Keychain to ~/.docker/config.json.

docker login dtr.mapsandbox.net
Username: <YOUR DTR_USER>
Password: <YOUR DTR_PWD>
Login Succeeded

Docker Desktop Settings

If using Docker Desktop, make the following updates:

In Docker Settings → Kubernetes:
- Enable Kubernetes
In Docker Settings → Resources:
- Set CPU to 8
- Set Memory to at least 20GB on 32GB systems (recommend 32GB on 64GB systems)
- Set Swap to 4GB
- Set Disk image size to at least 128GB

Disable Smart Quotes

These steps prevent macOS from automatically converting quote and dash characters to special characters.

Go to the Apple menu and choose System Preferences.
Select Keyboard.
Select the Text tab.
Uncheck Use smart quotes and dashes.

Show / Hide Hidden Files

Within a Finder window, press Command-Shift-. to toggle between hiding and showing all files. This setting remains sticky through your Finder sessions.