Local Development

This guide walks you through setting up a local development environment for monetr on macOS or Linux. If you are using Windows, it is still possible to run the development environment locally. However, it is not documented at this time.

Prerequisites

At the time of writing this, monetr requires Plaid credentials for development. Among other credentials, documentation on how to retrieve them can be found here: Developing > Credentials

Clone the repository

To get started, clone the monetr repository from GitHub (opens in a new tab) or from your fork.

git clone https://github.com/monetr/monetr.git
cd monetr

The rest of the commands in this guide are issued from this directory.

Dependencies

monetr does require a few tools to be installed locally in order to develop or build it. These tools are outlines below:

Required

• Node (>= 16.0.0)
• npm (>= 8.0.0)
• git (>= 2.0.0)
• Go (>= 1.20.0)
• CMake (>= 3.23.0)
• GNUMake (>= 4.0)

The tools above are the minimum tools required in order to build and work on monetr locally. But if you intend to run the complete development environment locally or if you plan on creating release builds of monetr you will also need:

Optional

• Docker (>= 20.0.0): Docker (and Docker Compose) are used to run the local development environment for monetr, allowing you to have the entire application and all of it's features with hot-reloading.
• Ruby (>= 2.7): Ruby is required to run licensed which is used to generate third-party-notice files, these show all of the dependencies of monetr and their licenses. This is embeded at build time for releases.
• Kubectl (>= 1.23.0): Kubectl is used to deploy monetr to a Kubernetes cluster. At the moment this is only used in CI/CD pipelines for deployying monetr to the Staging and Production clusters.

Mac Specific

macOS can ship with a version of make that is outdated. It is recommended that you use brew or any other preferred method to install the most recent version of GNUMake on your Mac. This will not break anything that is already using make, but will make sure that your version is compatible with the monetr Makefiles.

For example; you should see something like this for your make version.

make -v
# GNU Make 4.3
# Built for x86_64-apple-darwin20.1.0
# Copyright (C) 1988-2020 Free Software Foundation, Inc.
# License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
# This is free software: you are free to change and redistribute it.
# There is NO WARRANTY, to the extent permitted by law.

Configuration & Credentials

At the moment monetr requires at least Plaid credentials in order to run properly, even for development. You can read more about obtaining these credentials here: Credentials

The makefile will look for these development credentials and some configuration options in the following path:

$HOME/.monetr/development.env

You can create the file manually like this:

mkdir $HOME/.monetr
touch $HOME/.monetr/development.env
vim $HOME/.monetr/development.env

Once you've opened this file you'll need to provide the Plaid Client ID as PLAID_CLIENT_ID and Plaid Client Secret as PLAID_CLIENT_SECRET here.

CMake

monetr uses CMake as the primary build system, it is also used for running the tasks for local development. If you want to use a custom CMake configuration you can create a CMakeUserPresets.json file in the project directory (it will be ignored by Git) and populate it with the configuration variables you want to override. If you want to always use a specific preset when running general make targets you can create a .cmakepreset file in the project directory. Inside that file you can put the name of the preset you want to use by default. Or you can pass CMAKE_PRESET=... when running a make target.

Starting It Up

With the above requirements installed. You should be able to spin up the local development environment that runs inside of Docker compose.

This command will also load any of the environment variables specified in the development env file (mentioned above) into the monetr container where the API is running.

make develop

This will install node modules in the project's directory, as well as start up the containers needed for monetr to run locally. This command will exit automatically once all the containers are healthy. If you want to follow along while it is starting up you can use the make logs command in another terminal inside the project directory.

Working

Congratulations, you should now have monetr running locally on your computer. The develop task will print out some basic information for you. But if you missed it, you can access the development version of monetr at http://monetr.local.

If you are working on documentation then that can be accessed at http://monetr.local/documentation.

Almost all of monetr's code is setup to hot-reload as you make changes. The documentation, Go code and React UI will all automatically reload as changes are made. Changes to the Go code will not invoke a browser refresh of any sort though, so to observe a new behavior in the API you will need to refresh or make the API call again.

Local Services

As part of the local development stack, several services are run to support monetr. These services include:

• minio (opens in a new tab) As an S3 storage backend. The console is accessible via http://localhost:9001 when the local environment is running.
• local-kms (opens in a new tab) An AWS KMS compatible local development API. This is used for encrypting secrets in the local development environment.
• mailhog (opens in a new tab) An SMTP server that allows emails to be sent without really sending them. This is used to validate and test communication functionality locally. This service is accessible via https://monetr.local/mail when the local environment is running.

Debugging

The monetr container running the API has delve (opens in a new tab) included. If you prefer to work using a step-debugger you can connect your editor to it. You will need to reconnect your editor each time it reloads, but it is very easy to make your changes and then hit debug and let your breakpoints be hit.

Delve is available via port 2345 on localhost. I'm not sure what the configuration will be for every editor to connect to it; but this is a screenshot of IntellJ IDEA's configuration for remote debugging.

Running Tests

monetr requires a PostgreSQL instance to be available for Go tests to be run. At the moment there isn't a shorthand script to provision this instance. But an easy way to do so is this:

docker run -e POSTGRES_HOST_AUTH_METHOD=trust --name postgres --rm -d -p 5432:5432 postgres:14

This will start a PostgreSQL instance in Docker (or remove an existing one) and make it available on locahost:5432 as well as not require authentication. This makes it easy for tests to target it.

If tests are run via make then nothing more needs to be done. However, if you want to run tests directly from your editor or other tools you will need to run the database migrations.

make migrate

Will run all schema migrations on the PostgreSQL database on your localhost container.

Tests can be run using the go test CLI, or all tests can be run using:

make test

Running Storybook

monetr now provides a storybook setup for working on UI components outside of running the entire application locally. To start storybook you can run the following command.

make storybook

This will kick off the storybook server and build process. Once it is ready it will open the storybook in your default browser. You can then make changes to the components in the stories and see the changes in real time without needing to run the entire application stack locally.

NOTE At the moment storybook does not work with the CMake development tooling.

Cleaning Up

Once you have finished your work and you want to take the local development environment down you have a few options.

Shutting Down Development Environment

If you want to completely shut everything down then you can run the following command:

make shutdown

This removes the Plaid links that are active, takes down the Docker compose containers, removes their volumes.

Completely Clean up

If you want to completely start fresh you can run the following make task. This will shut down the local development environment if it is running, but it will also delete any files created or generated during development. This deletes your node_modules folder, any submodules, and generated UI code.

make clean

This should leave the project directory in a state similar to when it was initially cloned.