Development Environment Setup

Homebrew

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

git

Install from https://git-scm.com/download/mac

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

git config --global user.name "<NAME>"
git config --global user.email "<EMAIL>"

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" | bash

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

If you have any issues installing due to the version of bash that comes with your Mac, you can install a newer version via Homebrew with brew install bash, then set it as your default shell using chsh -s /usr/local/bin/bash. You will need to restart your terminal for this change to take effect.

Java

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

Our current default Java 21 version is Temurin 21.0.5:

sdk install java 21.0.5-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

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 using SDKMAN:

sdk install maven

Check your install for any errors:

mvn --version

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. 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.

Copier

Copier and related NGSS tools are currently in preview but will eventually be the mechanism to initialize and update DevOps and Backstage configuration files for NGSS-standard projects.

Copier is used to generate and maintain NGSS-standard files, such as Kubernetes manifests, Skaffold configuration files, and Backstage catalog entries for your projects. Copier’s CLI can be used directly or via the ngss-filegen-maven-plugin (filegen) wrapper when using Maven. See the Copier Templates section for more information.

Install using pipx (recommended):

# Install pipx if needed (macOS)
brew install pipx
pipx ensurepath

# Install Copier
pipx install copier

For Docker-based installation (no Python required) or Maven plugin integration, see the full Copier Installation Guide.

To test pre-release (RC) versions of templates, add --prereleases to Copier CLI commands or -Dcopier.prereleases to Maven goals. See Testing Pre-Release Versions for details.

For migrating an existing filegen 5.x or below (ngss-maven-tiles 2.9 or below) project to filegen 6.x (ngss-maven-tiles 2.10+) with Copier support, see the migration guide.

Skaffold / Kustomize

Install Skaffold and Kustomize, set up your environment according to the documentation:

Skaffold and Kustomize Setup

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.

Follow the migration guide instructions to install and configure it for your environment.

Docker Desktop

Alternately, you can use Docker Desktop for 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 --no-quarantine headlamp

There are links to other monitoring tool options on the K8s Monitoring Tools page.

IntelliJ

Most developers use IntelliJ as their preferred IDE. Download IntelliJ Ultimate here.

Open a Project

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

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

PlantUML Integration

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

Install PlantUML. From a terminal, execute brew install plantuml.
Install the PlantUML4Idea plugin. In IntelliJ, go to IntelliJ → Settings → Plugins → search for "PlantUML", and install the PlantUML4Idea plugin.
Configure the PlantUML plugin. In IntelliJ, go to IntelliJ → Settings → Languages and Frameworks → PlantUML. In the Graphviz dot executable field, enter /opt/homebrew/bin/dot and select OK. Restart IntelliJ for this to take effect.

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.