docs: update dev docs with buck / nix info

.github/workflows/buck2-test.yaml

@@ -23,10 +23,10 @@ jobs:
           for LABEL in $(jq -r '.[]' < labels.json); do
             case "$LABEL" in
               dashboard|consent)
-                ARGS+=" //apps/$LABEL:test"
+                ARGS+=" //apps/$LABEL:test-unit"
                 ;;
               core)
-                ARGS+=" //core/api:test"
+                ARGS+=" //core/api:test-unit"
                 ;;
             esac
           done

README.md

@@ -3,29 +3,29 @@
 [![Mattermost](https://img.shields.io/badge/chat-on%20mattermost-blue?style=social&logo=mattermost)](https://chat.galoy.io)
 [![GitHub Repo stars](https://img.shields.io/github/stars/GaloyMoney/galoy?style=social)](https://github.com/GaloyMoney/galoy/stargazers)
 [![Twitter Follow](https://img.shields.io/twitter/follow/GaloyMoney?style=social)](https://twitter.com/GaloyMoney)
-### 💡 Get help
+## 💡 Get help
 [Q&A](https://github.com/GaloyMoney/galoy/discussions) or [Mattermost 💬](https://chat.galoy.io)
 
-### TLDR
+## TLDR
 
 Galoy is an opinionated bitcoin banking platform.
 
 This repo represents the main api that brings all functionality together.
-Take a look at the [Quickstart](./quickstart) if you want to take it for a spin.
 
-### Responsible disclosure 
+
+## Responsible disclosure 
 
 Found critical bugs/vulnerabilities?
 Please email them [email protected] Thanks!
 
-### Get Started
+## Get Started
 
-Want to try it out and contribute? Checkout the [dev documentation](./DEV.md) to deploy locally with a docker compose script.
+Want to try it out and contribute? Checkout the [dev documentation](./docs/DEVELOPMENT_ENVIRONMENT.md) to deploy locally with a docker compose script.
 
 If you have questions, you can [join our Workspace](https://chat.galoy.io)
 
 For an overview of all relevant repository checkout [awesome-galoy](https://github.com/GaloyMoney/awesome-galoy).
-### Galoy-Backend features
+## Galoy-Backend features
 
 - GraphqlAPI:
   - Public API following industry best practices
@@ -80,13 +80,90 @@ For an overview of all relevant repository checkout [awesome-galoy](https://gith
   - Mobile clients can receive notifications of balance changes in real-time
   - Daily notification of balance for active end users
 
-### Tech Stack
+## Local Development Setup
+
+Running the Galoy software locally can be done in a variety of ways, but this abbreviated section will focus on a single method for
+getting your environment ready to run the stack.
+For more information and options on running Galoy locally, see the [development environment documentation](./docs/DEVELOPMENT_ENVIRONMENT.md).
+
+### (1) Choose a Supported Platform
+
+Currently developming on MacOS and Linux is supported.
+
+### (2) Install Dependencies
+
+Install dependencies on your chosen platform.
+
+- **1)** [`nix` with flakes enabled](https://github.com/DeterminateSystems/nix-installer)
+- **2)** `docker` from [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [Docker Engine](https://docs.docker.com/engine/)
+- **3a)** [`direnv`](https://direnv.net) version `>= 2.30` installed
+- **3b)** [`direnv` hooked into your shell](https://direnv.net/docs/hook.html)
+
+For `nix`, we highly recommend using the [Determinate Nix Installer](https://github.com/DeterminateSystems/nix-installer).
+
+For `docker`, the Docker Desktop version corresponding to your native architecture should be used.
+
+For `direnv`, you can install it with [your package manager of choice](https://direnv.net/docs/installation.html).
+However, if you're unsure which installation method to use or your package manager does not provide a compatible version,
+you can use `nix` itself (e.g. `nix profile install nixpkgs#direnv`).
+
+> We recommend using [the upstream docs for hooking `direnv` into your shell](https://direnv.net/docs/hook.html), but here is an example on how to do it
+> on a system where `zsh` is the default shell.
+> In this example, the following is added to the end of `~/.zshrc`.
+>
+> ```zsh
+> if [ $(command -v direnv) ]; then
+>    eval "$(direnv hook zsh)"
+> fi
+> ```
+
+### (3) Enter the Repository Directory
+
+All commands need to be run from the `nix` environment.
+Since `direnv` is installed _and_ hooked into your shell, you can `cd` into
+the repository and `nix` will boostrap the environment for you using the flake.
+
+_Please note: you may notice a large download of dependencies when entering the repository for the first time._
+
+### (4) Running the Stack
 
-- GCP, Kubernetes, Terraform, Helm, Concourse, Docker
-- Opentelemetry, Prometheus
-- Bitcoind, LND, Specter, RideTheLightning, Loop, Lndmon, Pool
-- PostgreSQL, MongoDB, Redis
-- NodeJS
-- Typescript
-- GraphQL
-- React + React Native
+We use [**buck2**](https://github.com/facebook/buck2) to run the stack, run and build individual services and libraries, perform lints and tests, etc.
+
+_Before continuing, you should stop any locally running services to avoid conflicting ports with the stack.
+Some of the services that will run include, but are not limited to the following: PostgreSQL, OpenTelemetry, MongoDB.
+
+Check if you are ready to run the stack before continuing.
+
+```bash
+buck2 run dev:healthcheck
+```
+
+You may notice some checks related to resource limits.
+On macOS and in WSL2 in particular, we recommend significantly increasing the file descriptor limit for `buck2` to work as intended (e.g. `ulimit -n 10240`).
+_Please note: the new file descriptor limit may not persist to future sessions._
+
+Once ready, we can build relevant services and run the entire stack locally.
+
+```bash
+buck2 run dev:up
+```
+
+Once Tilt starts, you can check on the status of all services by accessing the UI through the given port on your local host (e.g. [http://localhost:10350/](http://localhost:10350/)).
+Every service should eventually have a green checkmark next to them, which ensures that they are in "ready" states.
+
+### (6) Troubleshooting in Tilt
+
+If some services failed to start, you can restart them on the Tilt dashboard.
+
+### (7) Tearing Down the Stack
+
+The following command will stop all running services and containers.
+It will also remove the containers and, consequentially, the data held in them.
+
+```bash
+buck2 run dev:down
+```
+
+## Run integration tests with galoy as a dependency?
+
+Take a look at the [Quickstart](./quickstart) if you want to take it for a spin.

docs/BUCK2.md

@@ -0,0 +1,120 @@
+## [buck2](https://github.com/facebook/buck2)
+
+This document contains information on using `buck2` within this repository.
+We recommend using the `buck2` binary provided by our [Nix flake](../flake.nix) to ensure compatible versioning.
+
+## Terminology
+
+- A "target" is an instantiation of a rule
+- A "rule" is a library-esque function that can be buildable, runnable and/or testable
+- A "buildable" rule (`buck2 build`) only runs when affected sources are changed, and _ignores_ environment variables and passed down command-line arguments
+- A "runnable" rule (`buck2 run`) runs upon every invocation, and _accepts_ environment variables and passed down command-line arguments
+- A "testable" rule (`buck2 test`) runs upon every invocation and is similar to a runnable rule, but collects test metadata and is intended for sandboxed environments (e.g. CI)
+
+## The Shape of `buck2` Commands
+
+All `buck2` commands follow similar syntax.
+
+```shell
+<ENV> buck2 <CMD> <PATH/TO/DIRECTORY/WITH/BUCK>:<TARGET> -- <ARGS>
+```
+
+You can use pseudo-relative pathing to access targets.
+You cannot use relative parent directories (e.g. `../../path/to/directory/with/BUCK`), but you can
+use child relative directories, like in the example below.
+
+```shell
+buck2 run apps/consent:test-integration
+```
+
+However, you can always use the `//` prefix to start from the root, regardless of your current
+working directory in the repository.
+
+```bash
+# Let's change our current working directory to somewhere in the repository.
+cd apps/dashboard
+
+# Now, let's build using a BUCK file somewhere else in the repository.
+buck2 build //apps/consent
+```
+
+You may have noticed in the example above, we could build `apps/consent` without writing `apps/consent:consent`.
+If the target shares the same name as the directory, you do not have to write the name.
+
+```bash
+# This...
+buck2 build apps/consent
+
+# is the same as this...
+buck2 build apps/consent:consent
+
+# and this...
+buck2 build //apps/consent
+
+# is the same as this.
+buck2 build //apps/consent:consent
+```
+
+## I don't have syntax highlighting when viewing `BUCK` or prelude files. Help!
+
+Both `BUCK` files and the rules it uses are written in [Starlark](https://github.com/bazelbuild/starlark), which is a superset of Python.
+
+There is an [upstream VS Code extension](https://github.com/facebook/buck2/tree/main/starlark-rust/vscode)
+that you can build locally using `npm`.
+After building it, you can install the `vsix` file as an extension in VS Code.
+
+One great thing about the extension is that you can use "Go To Definition" in VS Code to follow the path of where a rule
+comes from and how it's written.
+
+## Where do the rules come from?
+
+There are two directories where the rules come from:
+
+- **[prelude](../prelude):** the vendored, [upstream standard library](https://github.com/facebook/buck2-prelude) with rules for common use cases and programming languages
+  - **Common use case example:** `sh_binary` is provided as a way to run shell scripts
+  - **Programming language example:** `rust_library` is a provided as a way to add buildable Rust library targets
+  - **Side note:** this must be kept up to date in conjunction with the `buck2` binary
+- **[toolchains](../toolchains/*):** our custom toolchains to use pnpm (which is not supported out of the box)
+  - **Example:** `tsc_build` uses tsc to output compiled javascript
+
+## How do I view all targets available for a given directory?
+
+Run the following command, but do not forget the `:` at the end.
+
+```shell
+buck2 targets <PATH/TO/DIRECTORY/WITH/BUCK>:
+```
+
+Here is an example:
+
+```shell
+buck2 targets //core/api
+```
+
+## Why isn't this new file I added available during builds?
+
+Expanding on the [terminology](#terminology) section, "buildable" targets only use files that are explicitly provided.
+If your new file isn't available during builds, you likely need to do one of two things:
+
+- Use the `export_file` rule to ensure the file is available for builds
+- Check the `srcs` attribute of a rule, if applicable, to ensure the file is in the sources tree
+
+## How do I run Rust tests with `buck2`?
+
+Check out the [RUNNING_RUST_TESTS](./RUNNING_RUST_TESTS.md) guide!
+Essentially, you'll use the following pattern:
+
+```shell
+# Pattern for unit tests
+<ENV> buck2 run <PATH/TO/DIRECTORY/WITH/BUCK>:test-unit -- <ARGS>
+
+# Pattern for integration tests
+<ENV> buck2 run <PATH/TO/DIRECTORY/WITH/BUCK>:test-integration -- <ARGS>
+```
+
+## Where are `buck2` users hanging out?
+
+[![Discord Server](https://img.shields.io/badge/discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/P5Tbrt735m)
+
+If you are looking to find other `buck2` users and/or ask questions, share ideas and share experiences related to `buck2`, check out the unofficial ["Buck2 Fans" Discord server](https://discord.gg/P5Tbrt735m).
+