Overview
This document is intended to provide the quickest path to a fully functional development environment for developers planning to contribute to the Check-Ins project using MacOS.
Install Homebrew
Homebrew is the missing package manager for macOS. For complete information on using Homebrew, visit https://brew.sh
The fastest path to installing Homebrew is to run the following from the command line:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
Before the script above, it’s recommended you review the script contents at https://raw.githubusercontent.com/Homebrew/install/master/install.sh. This will ensure you understand what the script is doing before running it.
If you run into any hiccups during installation, visit https://brew.sh/ for more information.
Shell Completions (optional)
For the most recent instructions for enabling command shell auto-completions, see the Homebrew Shell Completion Instructions for bash, zsh, and fish.
Install Git
Git is a distributed version control system that is used by the Check-Ins project. It is available via Homebrew and may already be installed on your Mac.
To check if git is installed, run the following command:
git --version
If git is not yet installed on your Mac, you may be prompted to install the XCode command line tools. To install XCode command line tools run command xcode-select --install
.
You can install git via Homebrew:
brew install git
Install Hub
Since this project is hosted on GitHub, using Hub will make many common tasks more convenient. You can install hub via Homebrew by running the following command:
brew install hub
Hub is an alternative to the GitHub CLI. If you prefer to use the GitHub CLI, you can install it with brew install gh
. A list of differences between the two can be found in the GitHub CLI documentation. If you choose to use the GitHub CLI, skip the following steps for creating a git alias.
You may wish to use hub
as a drop-in replacement for git
. To do this, you can create a git alias.
Create a git alias (optional)
If your default shell is zsh (macOS default) then add the following line to your ~/.zshrc
file. For bash, add the line to
your .bash_profile
or .bashrc
file.
alias git=hub
SSH Keys
If you haven’t already, you will want to configure git to use ssh for connecting to GitHub. If you’re using gpg-agent for SSH authentication, ensure your GPG keys are added to the agent.
Install JDK
JDK is required to build and run the Check-Ins project. You can install a specific version of the JDK using SDKMAN. First, install SDKMAN by running the following command:
curl -s "https://get.sdkman.io" | bash
Before running the above command, it’s recommended you review the script contents at https://get.sdkman.io. This will ensure you understand what the script is doing before running it.
Then, install the JDK with:
sdk install java 21.0.4-tem
sdk use java 21.0.4-tem
sdk default java 21.0.4-tem
We also support using GraalVM Community Edition to build native executables. In order to test the GraalVM-built native executables, you will need to install GraalVM as well:
sdk install java 21.0.2-graalce
You can switch to the GraalVM compiler by running:
sdk use java 21.0.2-graalce
Please note JDK 21
is the latest version at the time of writing. See the .java-version
file in the project root for the version of the JDK required for this project. You will also find versions in server/Dockerfile
.
Install NVM
Note: If you have previously installed NVM, you should update it to the latest version. As an alternative to NVM, the Fast Node Manager can be used as well.
To install or update NVM, run the following from the command line:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
Where v0.40.1
is the latest version of NVM at the time of writing. You can find the latest version on the NVM Releases page on GitHub.
After installing NVM, you will need to restart your terminal or run the following command to start using NVM:
source ~/.nvm/nvm.sh
See the NVM GitHub page for additional help and information.
Enable NVM Shell Completions (optional)
Add the following to the appropriate shell config (.zshrc, etc.)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
Install Correct Node Version
Install and use the correct node version for the project.
nvm install 22.9 #this will download the latest patch version
nvm use 22.9 #this will use the latest patch version
If you are not working on other node projects, you may want to set this as your default. Otherwise, you will need to make sure you are using the correct version everytime you restart your terminal. To set your default, please use the following:
nvm alias default 22.9 #this will set the latest patch version to default
Install Yarn
brew install yarn
You should now have yarn
available on your command line. Check the version with:
yarn --version
You should be using Yarn 1.22.19 or later.
Install Podman
If you are using Docker Desktop, you can skip this section, and set an environment variable via
export USE_DOCKER_DESKTOP=1
in your shell profile. This will enable Ryuk for cleaning up old containers under testing.
This project uses Podman for containerization. Podman is a daemonless container engine for developing, managing, and running Open Container Initiative containers. It is an alternative to Docker and is available without fee for macOS via Homebrew.
To install Podman, run:
brew install podman
To install podman-compose, run:
brew install podman-compose