$ cd -

Common Java developer Macbook setup

Last edit: 2021-12-16

I'm a Java developer. This is how I set up a new Macbook. It evolves over time and ymmv. My standard disclaimer applies.


Install iTerm2

I usually start by installing iTerm2. I don't think I could handle using the built-in "Terminal" application. After opening iTerm, an important thing you should remember to do is enable shell integration.

Oh My Zsh!

After that, I want Oh My Zsh! installed. (See the bottom of their page to find out how.) This is a vital necessity.

Install Homebrew

The next thing I am going to need to do is to install Homebrew. Homebrew allows me to install a number of common software programs with much lower effort.

See the instructions for installing Homebrew and install it accordingly.

Install git

Once Homebrew is installed, I can use brew to install git:

    $ brew install git
This also lets me easily get upgrades later.

If you prefer, though, you can install git the hard way.

Note that use of git to access your repositories requires the configuration of SSH and PGP keys, which is covered below.


Before going any further, I will need access to my accounts. And that means restoring my KeePassXC database and key file to the appropriate places on this new machine. I will not go into details here. The KeePassXC documentation covers every available scenario.

I install KeePassXC with Homebrew:

    $ brew install --cask keepassxc

SSH key pair

One of the first things I need to do is create a new SSH key pair for this device. I do this on each new device, and I do not reuse any SSH key pair across devices. If the device ever gets lost or stolen, then I don't have to worry about it. If that ever happened, I would simply disable that particular key pair from having access to the various git (or other) platforms that I've allowed it on, and be done with it.

You may take a different approach and that is fine. It is a tradeoff between either replacing the key on every device you use or replacing the key on every platform you use. For me, replacing the key on platforms like GitHub and GitLab is easier than going to each of my devices in turn and replacing the key there, so I choose this way.

I set up the key pair according to the A good way to set up SSH keys for Git on Macbooks article. When I have time, I'll copy that content here instead.

Once I have my SSH key pair created, I also supply the public key to my GitHub.com and GitLab.com accounts according to their respective documentation. Don't forget to update the $HOME/.ssh/config with the correct configuration, and save the key pairs into KeePassXC.

PGP key pair

Next, I import PGP key pairs for whatever email address(es) I need to use with these different Git platforms (or otherwise).

My general approach for securely transferring PGP keys from machine to machine is with ssh. You can log into the machine with the PGP key pair you want and push it to your new machine with:

    $ gpg --export-secret-key SOMEKEYID | ssh othermachine gpg --import

Or you can log into the new machine and pull the PGP key pair in question with:

    $ ssh othermachine gpg --export-secret-key SOMEKEYID | gpg --import

Setup for signing commits

Next, I set up git accounts with the appropriate keys so that I always use signed commits. (If you don't do this, why don't you? As a developer, I can't imagine a good reason. It feels irresponsible to me to not sign commits.)

Here are the articles for three popular git platforms that have to do with signing commits:

Generally the above instructions include configuring your local git with the right signing key, but I want to be explicit on this point. You MUST execute a command like this in order to configure git to use your PGP key:

    $ git config --global user.signingkey SOMEKEYID

Furthermore, the above signing key MUST match the email configured in the user.email parameter. Once you think you have configured everything correctly, you will probably want to just double-check that both are set, and that they are set to the correct values. You can do that with:

    $ git config user.email && git config user.signingkey

Finally, if you actually have multiple Git repositories that are all signed with different keys, then you'll have to figure out which one you use the most often, and make it the global value, with:

    $ git config --global user.signingkey SOME_KEY_ID
    $ git config --global user.email THE_MATCHING_EMAIL

Then, you also need to go to each disparate repository, and configure their specific email and signing key. The commands for this are the same as above except they omit the --global flag.

If you don't understand git configuration, read the relevant section in Pro Git.

Setup Development folder

My preference is to create a new folder, Development, stored at $HOME/Documents/Development, where all source control repositories are checked out and organized into a hierarchical fashion.

This usually means the following sequence of commands on a modern Macbook with zsh (zsh replaced bash when macOS Catalina came out):

    $ cd $HOME
    $ mkdir -p $HOME/Documents/Development
    $ ln -s $HOME/Documents/Development $HOME/dev
    $ cd dev
    $ mkdir github.com
    $ mkdir gitlab.com
    $ mkdir {{URL of private Git repository}}
    $ mkdir {{you probably get the picture...a directory for each Git platform I use}}

Install Java Tools

The next step, of course, is to get some Java tooling installed. At a bare minimum, this means the following.

I install SDKMan!, and then use it to install and set an appropriate default JDK.

I install Apache Maven.

I may also install gradle if I have any applications using it.

I install the JetBrains Toolbox, and then I use it to install an appropriate version of IntelliJ IDEA. I also use Toolbox to install the idea cli.

There are probably others I am forgetting, but which I will be adding here in the future.


Finally! I can now checkout my dotfiles. I created my dotfiles repository according to the popular streakycobra method. This is described better by an Atlassian tutorial so if you don't have dotfiles that's the best place to go to learn how to set up dotfiles.

The dotfiles are a bit of a chicken-and-egg proposition because as you have observed so far, I had to get git installed and configured up to this point, but I'm about to check out my dotfiles and overwrite that configuration. So be wise and back up your .gitconfig file first. The same applies to anything else you may have heretofore configured.

Anyway, I can now navigate to my dev folder, clone my dotfiles repo locally, and then set them up.

Checkout and build code

At this point, I will probably clone a bunch of repos and start building them with Maven. This will cause a massive dump of artifacts to my local Maven cache, and that is the point. I know that this step will take awhile, and so I've ordered everything above to get me here as quick as possible.

Once everything is building, now is a good time for a break.

Take a break


Fix broken stuff

I will check back periodically, and probably I will find a bunch of issues I need to fix.

Be happy

When stuff finally builds, it is really a great feeling! But we're not done yet.

Install helpful tools

Every mac user probably uses Rectangle because it is a superior window manager. I install it.

Next comes a better lightweight plain-text editor: TextMate. In fact, until I install TextMate, my ability to make commits to git is probably broken, since I configure git to use it for all commit messages.

Speaking of git, there are a couple really useful shell utilities that help with git's output a lot. And I mean A LOT! These are bat and delta. Special thanks to Aaron Davis for tipping me off on these. You don't even have to be a Java developer to appreciate bat and delta.

Next, I probably install and set up my own noted cli for taking notes.

I also install this software-quotes.dat fortune file, because it's fun to see a random quote like the below whenever I open a new iTerm window/pane.

    Let us change our traditional attitude to the construction of programs. Instead
    of imagining that our main task is to instruct a computer what to to, let us
    concentrate rather on explaining to human beings what we want a computer to

    Donald Knuth

That reminds me, I install lolcat so I can see these quotes in a rainbow of colors.

    $ brew install lolcat
To make sure that's in every new iTerm window or pane, I add this to my .zshrc file:
    fortune software-quotes | lolcat


I'll keep updating this with more but I think that covers most of the basics anyway. You may imagine that some or all of Slack, Postman, node, npm, Zoom, etc. end up on there too.


$ cd -