Developers need a Unix-ish environment for local development. This README provides instructions for developing on MacOS and Windows+WSL2 (using Ubuntu).
We recommend using VS Code as the code editor of choice.
In general, the necessary tools are:
- Bash
- A standard C toolchain (notably, a C compiler and
make
) - Git
- Docker
- Go
- Go analysis tools:
gopls
,dlv
,dlv-dap
,gopkgs
,go-outline
,goplay
,gomodifytags
,impl
,gotests
,staticcheck
goimports
(Used byscripts/dev gql
)- Node.js
- Yarn
- Ruby
direnv
pre-commit
(Installation requires Python)psql
(Postgres command-line client)jq
(Used for preprocessing Swagger JSON files)go-swagger
(Used for generating Go code based on Swagger files)
MacOS: Developers will need Homebrew to install dependencies, which can be installed with /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
.
Windows: Developers will need to install WSL2, set up an Ubuntu distro, then configure VS Code to work with WSL2.
- In Powershell running as admin, run
wsl --install
. - Reboot your computer to finish WSL installation.
- In a regular Powershell window, run
wsl --set-default-version 2
, then runwsl --install -d Ubuntu
. - In VSCode, install the Remote - WSL extension (ID:
ms-vscode-remote.remote-sdl
).
For developers on Windows+WSL, this repository should be cloned onto the Ubuntu filesystem. All installation instructions below should be run from within the Ubuntu environment, except for setting up Docker.
When working on the terminal in WSL, you may see the occasional ERROR: UtilConnectToInteropServer:307
error message. This is caused by this WSL issue. The easiest fix is to define a Bash function from this comment on that issue, then run that function whenever you see that error.
MacOS: Developers will need to install the bash
shell.
-
Ensure you are using the latest version of bash for this project:
-
Install it with Homebrew:
brew install bash
-
Update list of shells that users can choose from:
[[ $(cat /etc/shells | grep /usr/local/bin/bash) ]] \ || echo "/usr/local/bin/bash" | sudo tee -a /etc/shells
-
If you are using bash as your shell (and not zsh, fish, etc) and want to use the latest shell as well, then change it (optional):
chsh -s /usr/local/bin/bash
-
Ensure that
/usr/local/bin
comes before/bin
on your$PATH
by runningecho $PATH
. Modify your path by editing~/.bashrc
or~/.bash_profile
and changing thePATH
. Then source your profile withsource ~/.bashrc
or~/.bash_profile
to ensure that your terminal has it.
-
Windows+WSL: Ubuntu set up with WSL already has Bash as its default shell.
The Go analysis tools and the frontend package node-sass
depend on having a basic C toolchain installed.
MacOS: Developers should have this installed by default.
Windows+WSL: Developers can install this with sudo apt install build-essential
.
MacOS: brew install git
Windows+WSL: The default Ubuntu installation should have a recent version of Git installed. To install the latest version of Git, see the official installation instructions.
MacOS:
brew cask install docker
brew install docker-completion docker-compose docker-compose-completion
Now you will need to start the Docker service: run Spotlight and type in "docker", then select "Docker Desktop" in the results.
Windows+WSL:
- Install Docker Desktop for Windows.
- Enable WSL2 integration with the installed Ubuntu distro.
- Open Docker Desktop
- Click the gear icon to open settings
- Under Resources -> WSL Integration, enable the switch for "Ubuntu" under the "Enable integration with additional distros" heading.
MacOS:
Install the latest version of Go with brew install go
.
Windows+WSL:
- Download the
.tar.gz
file for the latest version of Go for Linux from the official Go site, making sure to save it to the Ubuntu filesystem. The easiest way to do this is to copy the download link, then usewget
to download it on the command line, i.e.wget https://golang.org/dl/go1.17.3.linux-amd64.tar.gz
. This will download the.tar.gz
to the current directory. - From the directory containing the
.tar.gz
file, extract it to/usr/local/go
, i.e. withsudo tar -C /usr/local -xzf go1.17.3.linux-amd64.tar.gz
. - Add
/usr/local/go/bin
to yourPATH
. The easiest way to do this is to add the following to your~/.bashrc
file:
export PATH="$PATH:/usr/local/go/bin"
Both MacOS and Windows+WSL developers will need to add the GOBIN
environment variable (which defaults to $GOPATH/bin
) to their PATH
, so tools installed with go install
can be called from the command line. Add the following to your ~/.bashrc
file:
export PATH="$PATH:$(go env GOPATH)/bin"
The goimports
tool is used by scripts/dev gql
to clean up autogenerated code. To install it, run go install golang.org/x/tools/cmd/goimports@latest
.
We currently support Node.js v16 for this repo; Node 17 support is currently blocked by this create-react-app
issue.
The easiest way to install this specific version of Node/npm is to use nvm
. To install nvm
, run
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
Reload your shell, then run nvm install
.
We use Yarn to manage our JavaScript dependencies. It can be installed with npm install --global yarn
.
MacOS: Ruby should be installed by default.
Windows+WSL: Install Ruby with sudo apt install ruby-full
.
MacOS: Install with brew install direnv
.
Windows+WSL: Install with sudo apt install direnv
.
All developers:
- Add the following line at the very end of your
~/.bashrc
file:eval "$(direnv hook bash)"
- Refer to instructions for other shells if you're using a shell other than bash.
- Restart your shell.
- To allow direnv in the project directory
direnv allow
.
Once this is setup, you should see direnv
loading/unloading environment
variables as you enter or depart from the project directory:
$ cd mint-app
direnv: loading ~/Project/mint-app/.envrc
direnv: export +EXAMPLE_ENV +EXAMPLE_ENV_ADDITIONAL +EXAMPLE_ENV_MORE ... ~PATH
$ cd ..
direnv: unloading
$
This repo uses pre-commit
to manage pre-commit Git hooks for maintaining several quality and stylistic standards; see .pre-commit-config.yaml
for details.
MacOS: Install with brew install pre-commit
.
Windows+WSL:
- First install Python's
pip
package manager withsudo apt install python3-pip
. - Then, install
pre-commit
withpip install pre-commit
. This should installpre-commit
in the~/.local/bin
directory. - Add this directory to your
PATH
. Add the following to~/.bashrc
:
export PATH="$PATH:$HOME/.local/bin"
All developers:
- From the root of this repo, run
pre-commit install
to set up a Git pre-commit hook in.git/hooks/pre-commit
. - Then, run
pre-commit install-hooks
to install the environments for this project's specific hooks.
The Postgres command-line client is needed for running database-related scripting commands, but the database server doesn't need to be installed; it can be handled with Docker.
MacOS: Install with brew install postgres
. This installs the Postgres server as well; if this is an issue, see this StackOverflow Q&A for alternatives.
Windows+WSL: Install with sudo apt install postgresql-client
.
To install the frontend's dependencies, run yarn install --frozen-lockfile
. The --frozen-lockfile
flag will install the exact versions of all dependencies that are specified in yarn.lock
;
jq
is used for preprocessing the Swagger file from CEDAR's Intake API, before we run code generation. It may already be installed on your system, but if not:
MacOS: Install with brew install jq
.
Windows+WSL:: Download and install with sudo apt-get install jq
.
go-swagger
is used for generating code based on Swagger files that describe the CEDAR APIs.
We currently use v.0.28.0
of this tool, and the binaries for it can be found here. M1 Mac users should use the arm64
binaries, while other Linux distros should be able to use the amd64
binaries.
Windows+WSL: From the Ubuntu command line, navigate to the root of this repository, then run code .
to open VS Code with this repository opened.
All developers:
- VS Code will recommend installing the extensions specified in
.vscode/extensions.json
. Install all of them.
- Windows+WSL: The GitLens extension will likely not work. It is dependent on another extension which VSCode installs on the windows side. If it doesn't work, you can safely ignore it.
- The Go extension should prompt you to install the analysis tools it uses. Install all of them. See these instructions for more details.
With all dependencies installed, you should be able to start the application. See these instructions on how to use the development script to run the application locally.