Flesh out dev setup documentation

Author: prestoncabe

README.md

@@ -42,40 +42,114 @@ If you are interested in getting involved with the project, check out [our page
 
 [library-api](/library-api) contains a library of pre-built benefits and eligibility rules, suitable for including in custom screeners and for standing up a standalone eligibility API.
 
-## Local Development Setup
+## Development Setup
+
+### In the Cloud (Github Codespaces)
+
+This is the easiest way to get started with development if you like having a cloud-based development environment. Just click the badge:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/CodeForPhilly/benefit-decision-toolkit)
+
+Once you create a new codespace, the included Devcontainer will build and configure the project. This takes several minutes the first time, so be patient!
+
+### On Your Local Machine
 
 Clone this repository:
+
 ```bash
 git clone https://github.com/CodeForPhilly/benefit-decision-toolkit.git
 ```
 
 Go to the project's root directory:
+
 ```bash
 cd benefit-decision-toolkit
 ```
 
-To setup using the pre-defined [Devbox](https://www.jetify.com/docs/devbox/) configuration:
-*Note that this installs Devbox and Nix (if they aren't already installed).
+From here, you have 3 options:
+- Use [Devbox](https://www.jetify.com/docs/devbox/) (recommended),
+- Use [Devcontainer in VS Code](https://code.visualstudio.com/docs/devcontainers/containers), or
+- DIY (not recommended)
+
+#### Option 1: Devbox (recommended)
+
+We use [Jetify Devbox](https://www.jetify.com/docs/devbox/) to declare and manage project development dependencies. This makes it easy to setup the project and reduces *"works on my machine"* issues. It uses the Nix Package Manager under the hood, which results in higher performance compared to container-based solutions.
+
+To install devbox (and Nix) and configure your machine for development:
+
 ```bash
 bin/install-devbox && devbox run setup
 ```
 
-If you don't want to use devbox/nix, then you can install system dependencies (e.g. JDK, Node, Maven) manually (see devbox.json for the list) and run:
+Then, to startup all the services/apps with the default configuration, run:
+
 ```bash
-bin/setup
+# uses process-compose under the hood
+devbox services up
 ```
 
-If using devbox, then run the shell to load dependencies:
+You can also run a shell in the context of Devbox with:
+
 ```bash
 devbox shell
-# Consider using direnv and/or the VS Code extensions (Devbox and Direnv) to automate this step.
 ```
 
-Then start apps as needed, e.g.:
+Or run a single command in the context of Devbox with:
+
+```bash
+# export data from the firebase emulators (they must be running!)
+devbox run -- firebase emulators:export ./dir
+```
+
+Tips:
+- Use the [Devbox direnv integration](https://www.jetify.com/docs/devbox/ide-configuration/direnv) to automatically start a Devbox shell whenever you navigate to the project directory.
+- If you develop in VS Code, then consider installing the [Devbox and Direnv extensions](https://www.jetify.com/docs/devbox/ide-configuration/vscode) to automatically start `devbox shell` in VS Code Terminal and otherwise manage Devbox via the Command Palette.
+- Edit the `.devboxrc` file (not in source control) to run custom commands every time you start a devbox environment. You can use this for things like disabling conflicting tools or adding project-specific shell aliases.
+
+#### Option 2: Devcontainer in VS Code
+
+This project comes with a devcontainer configuration that runs the Devbox/Nix environment inside the container itself. This is a good option for those used to a container-based workflow and don't mind the corresponding performance degradation as compared to native Devbox.
+
+To use the provided devcontainer, first open VS Code and install the `Dev Containers` extension.
+
+Then, use the command palette (Cmd+Shift+P or Ctrl+Shift+P) to run *"Dev Containers: Open Folder in Container..."* and select this project. It will take several minutes to build the container the first time.
+
+You should be prompted to install Docker if it isn't already installed.
+
+Once the container builds, startup all the services/apps in the default configuration by opening a Terminal in VS Code and running:
+
+```bash
+devbox services up
+```
+
+Note: the devcontainer automatically uses the equivalent of `devbox shell` in VS Code Terminal, so there is no need to run it manually.
+
+#### Option 3: DIY (not recommended)
+
+It is recommended to use Devbox, Devcontainer, or Codespaces to develop with this project because each of those methods draw from a single source of truth to build the development environment (devbox.json).
+
+If you insist on going your own way then you can install system dependencies (e.g. JDK, Node, Maven) manually (see devbox.json for the list) and run:
+
 ```bash
-cd builder-frontend && npm run dev
+bin/setup
+```
+
+Then to startup all the services/apps in the default configuration, install [process-compose](https://f1bonacc1.github.io/process-compose/) and run:
+
+```bash
+process-compose
 ```
 
-You can find additional instructions to work on each app within the project in their respective directories, which are linked above.
+Or to run services manually (without `process-compose`):
 
-Note that for the frontend apps, you will need a .env file from a teammate. Please do not commit this file to the repo.
+```bash
+# start the firebase emulators
+firebase emulators:start --project demo-bdt-dev --only auth,firestore,storage
+```
+
+```bash
+# then start up services one by one in new shells, e.g.:
+bin/load-root-env
+cd builder-api
+quarkus dev
+```

bin/setup

@@ -114,14 +114,20 @@ echo ""
 print_success "🎉 Developer setup completed successfully!"
 echo ""
 echo "📋 Next Steps:"
+echo ""
 echo "1. Environment Configuration:"
 echo "  a. If you plan to use devbox and develop against local emulators, then you are good to go!"
 echo "  b. If not using devbox and/or plan to develop against real Firebase services, then you might need help from a teammate to finish setting up your environment."
-echo "2. If using devbox, then:"
-echo "  a. Run 'devbox shell' within the project root directory to load dependencies. (https://www.jetify.com/docs/devbox/cli_reference/devbox_shell/)"
-echo "  b. Consider using the direnv integration to load dependencies automatically. (https://www.jetify.com/docs/devbox/ide_configuration/direnv/)"
-echo "  c. If you use VS Code, then consider installing the Devbox and Direnv extensions."
-echo "3. Run the web apps locally using 'npm run dev' from within builder-frontend and screener-frontend directories."
-echo "4. Run the library-api application using 'quarkus dev' within the library-api directory."
+echo "2. Run all main web app services locally in dev mode:"
+echo "  a. With devbox: 'devbox services up'"
+echo "  b. Without devbox: install then run 'process-compose'"
+echo "3. Other things to try:"
+echo "  a. Run 'devbox shell' to load the environment without running services."
+echo "  b. Consider using the direnv integration to load dependencies automatically."
+echo "  c. Consider installing the Devbox and Direnv extensions for VS Code."
+echo "  d. Run the library-api:"
+echo "    i. 'devbox shell'"
+echo "    ii. 'cd library-api'"
+echo "    iii. 'quarkus dev'"
 echo ""
 print_status "Happy coding! 🚀"