update docs

Vagrantfile

@@ -12,7 +12,7 @@
 # After a box is launched, use `vagrant ssh` to log in.
 #   - the code is in ${HOME}/bubble
 #   - API environment file is ${HOME}/.bubble.env
-#   - start the API server (local launcher) with `run.sh`
+#   - start the API server (local launcher) with run.sh
 #
 # There are a few environment variables that determine how the box is initialized,
 # described below.
@@ -104,7 +104,7 @@ Vagrant.configure("2") do |config|
          Once logged in:
           - the code is in ${HOME}/bubble
           - API environment file is ${HOME}/.bubble.env
-          - start the API server (local launcher) with \`run.sh\`
+          - start the API server (local launcher) with run.sh
 
          Enjoy!
          ==================================================================

bin/bactivate

@@ -16,12 +16,12 @@
 #   BUBBLE_PASS    : password for account. Default is password
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${BUBBLE_JAR}" ]] ; then
   die "BUBBLE_JAR env var not set and no jar file found"
 fi
 
 ACTIVATION_JSON="${1:?no activation json file provided}"
-${SCRIPT_DIR}/bput <"${ACTIVATION_JSON}" auth/activate - --no-login
+"${SCRIPT_DIR}"/bput <"${ACTIVATION_JSON}" auth/activate - --no-login

bin/bbuild

@@ -0,0 +1,42 @@
+#!/bin/bash
+#
+# Build the bubble jar
+#
+# Usage:
+#
+#    bbuild [no-clean] [debug|full|prod]
+#
+#  no-clean : if present, do not clean the `target` directory before building
+#
+#  debug    : a debug build, does not include anything else in the jar
+#  full     : a production build, creates a fat jar in `bubble-server/target/bubble-server-VERSION-full.jar`
+#  prod     : a production build, creates a slimmer jar in `bubble-server/target/bubble-server-VERSION-prod.jar`
+#
+# If debug/full/prod is not specified, the default is prod.
+#
+SCRIPT="${0}"
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
+
+CLEAN="clean"
+PROFILE=""
+if [[ -n "${1}" ]] ; then
+  if [[ "${1}" == "no-clean" ]] ; then
+    CLEAN=""
+    shift
+  fi
+  if [[ "${1}" == "debug" ]] ; then
+    PROFILE=""
+  elif [[ "${1}" == "full" ]] ; then
+    PROFILE="-Pproduction-full"
+  elif [[ "${1}" == "prod" ]] ; then
+    PROFILE="-Pproduction"
+  else
+    die "Invalid argument: ${1}"
+  fi
+else
+  # default
+  PROFILE="-Pproduction"
+fi
+
+mvn -DskipTests=true -Dcheckstyle.skip=true ${PROFILE} ${CLEAN} package

bin/bconst

@@ -19,17 +19,9 @@
 #
 #     bconst bubble.ApiConstants.ROOT_NETWORK_UUID
 #
-# Environment variables
-#
-#   BUBBLE_API     : which API to use. Default is local (http://127.0.0.1:PORT, where PORT is found in .bubble.env)
-#   BUBBLE_USER    : account to use. Default is root@local.local
-#   BUBBLE_PASS    : password for account. Default is password
-#   BUBBLE_INCLUDE : path to look for JSON include files. default value is to assume we are being run from
-#                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
-#
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 CLASS_AND_MEMBER="${1:?sole param should be something like: bubble.pkg.SomeClass.SOME_CONSTANT}"
 shift

bin/bdecrypt

@@ -5,8 +5,8 @@
 # Decrypt data using the Bubble database's encryption key
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${BUBBLE_DB_ENCRYPTION_KEY}" ]] ; then
   if [[ -f "${HOME}/.BUBBLE_DB_ENCRYPTION_KEY" ]] ; then
@@ -18,4 +18,4 @@ if [[ -z "${BUBBLE_DB_ENCRYPTION_KEY}" ]] ; then
   fi
 fi
 
-BUBBLE_DB_ENCRYPTION_KEY=${BUBBLE_DB_ENCRYPTION_KEY} exec ${SCRIPT_DIR}/bubble crypt -f decrypt "${@}"
+BUBBLE_DB_ENCRYPTION_KEY=${BUBBLE_DB_ENCRYPTION_KEY} exec "${SCRIPT_DIR}"/bubble crypt -f decrypt "${@}"

bin/bdelete

@@ -20,8 +20,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bdocker

@@ -31,14 +31,11 @@
 # If you want to run this unattended, set the LETSENCRYPT_EMAIL environment variable
 # in your ~/.bubble.env file or in your shell environment.
 #
+SCRIPT="${0}"
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
-function die {
-  echo 1>&2 "${1}"
-  exit 1
-}
-
-THISDIR="$(cd "$(dirname "${0}")" && pwd)"
-BUBBLE_DIR="$(cd "${THISDIR}/.." && pwd)"
+BUBBLE_DIR="$(cd "${SCRIPT_DIR}"/.. && pwd)"
 
 MODE=${1:?no mode specified, use build or run}
 

bin/bencrypt

@@ -5,8 +5,8 @@
 # Encrypt data using the Bubble database's encryption key
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${BUBBLE_DB_ENCRYPTION_KEY}" ]] ; then
   if [[ -f "${HOME}/.BUBBLE_DB_ENCRYPTION_KEY" ]] ; then

bin/bget

@@ -20,8 +20,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bgeti

@@ -20,8 +20,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bgeti1

@@ -20,8 +20,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bgetn

@@ -20,8 +20,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bgetn1

@@ -20,8 +20,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bmodel

@@ -17,8 +17,8 @@
 #   BUBBLE_SCRIPTS : location of run.sh script. Default is to assume it is in the same directory containing this script
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 UPDATE_OPT=""
 if [[ -n "${1}" && ( "${1}" == "-u" || "${1}" == "--update-all" ) ]] ; then

bin/bpost

@@ -22,8 +22,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bposte

@@ -21,8 +21,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bput

@@ -22,8 +22,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bpute

@@ -21,8 +21,8 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 URL="${1:?no URL provided}"
 shift

bin/bpyvenv.sh

@@ -9,14 +9,14 @@ function die {
   exit 1
 }
 
-BUBBLE_HOME="$(cd $(dirname ${0})/.. && pwd)"
+BUBBLE_HOME="$(cd "$(dirname "${0}")"/.. && pwd)"
 
-cd ${BUBBLE_HOME} || die "Error changing to ${BUBBLE_HOME} dir"
+cd "${BUBBLE_HOME}" || die "Error changing to ${BUBBLE_HOME} dir"
 
 if [[ ! -d "${BUBBLE_HOME}/.venv" ]] ; then
   python3 -m venv ./.venv || die "Error creating venv"
 fi
-. ${BUBBLE_HOME}/.venv/bin/activate || die "Error activating bubble venv"
+. "${BUBBLE_HOME}"/.venv/bin/activate || die "Error activating bubble venv"
 python3 -m pip install requests || die "Error installing pip packages"
 
 if [[ -n "${1}" ]] ; then

bin/brsync

@@ -9,17 +9,14 @@
 #
 #    BUBBLE_SSH_PORT  : If set, this port will be used instead of 1202
 #
+SCRIPT="${0}"
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${BUBBLE_SSH_PORT}" ]] ; then
   BUBBLE_SSH_PORT="1202"
 fi
 
-function die() {
-  echo 1>&2 "${1}"
-  exit 1
-}
-
-
 if [[ $(echo "${@}" | grep -c -- "-e ") -gt 0 || $(echo "${@}" | grep -c -- "--rsh") -gt 0 ]] ; then
   die "$0 does not work correctly when -e or --rsh is used, since it sets its own: ${@}"
 fi

bin/bscp

@@ -8,6 +8,9 @@
 #
 #    BUBBLE_SSH_PORT  : If set, this port will be used instead of 1202
 #
+SCRIPT="${0}"
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${BUBBLE_SSH_PORT}" ]] ; then
   BUBBLE_SSH_PORT="1202"

bin/bscript

@@ -21,10 +21,10 @@
 #                      bubble repo, bubble-models repo, or bubble-client and use include files from minimal model.
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
-BUBBLE_SERVER=$(cd $(dirname ${0})/.. && pwd)
+BUBBLE_SERVER="$(cd "$(dirname "${0}")"/.. && pwd)"
 
 CANDIDATE_INCLUDES="
 ${BUBBLE_SERVER}/src/test/resources/models/minimal/tests

bin/bssh

@@ -8,6 +8,9 @@
 #
 #    BUBBLE_SSH_PORT  : If set, this port will be used instead of 1202
 #
+SCRIPT="${0}"
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${BUBBLE_SSH_PORT}" ]] ; then
   BUBBLE_SSH_PORT="1202"

bin/bubble

@@ -24,8 +24,8 @@
 #   BUBBLE_SCRIPTS : location of run.sh script. Default is to assume it is in the same directory containing this script
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 function is_api_command {
   case "${1}" in

bin/bunlock

@@ -17,16 +17,16 @@
 #   BUBBLE_PASS    : password for account. Default is password
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
 
-REQUIRE_BUBBLE_USER=1
-REQUIRE_BUBBLE_PASS=1
-. ${SCRIPT_DIR}/bubble_common
+export REQUIRE_BUBBLE_USER=1
+export REQUIRE_BUBBLE_PASS=1
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${BUBBLE_API}" ]] ; then
   die "No BUBBLE_API env var defined"
 fi
-UNLOCK_KEY=${1:?no unlock-key provided}
+UNLOCK_KEY="${1:?no unlock-key provided}"
 
 echo "{\"name\":\"${BUBBLE_USER}\",\"password\":\"${BUBBLE_PASS}\"}" | \
-  ${SCRIPT_DIR}/bpost 'auth/login?k='"${UNLOCK_KEY}"'' - --no-login
+  "${SCRIPT_DIR}"/bpost 'auth/login?k='"${UNLOCK_KEY}"'' - --no-login

bin/bvagrant.sh

@@ -1,3 +0,0 @@
-#!/bin/bash
-
-vagrant box add ubuntu/focal64

bin/jq-all-vals

@@ -16,8 +16,8 @@
 #  prop-name : a property name
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
-ARG=${1:?no property provided}
+ARG="${1:?no property provided}"
 jq -r 'getpath(path(.. | select(.'"${ARG}"' != null))) | .'"${ARG}"'' 2> /dev/null

bin/mitm_pid

@@ -5,4 +5,4 @@
 # Print PID of currently-active mitmproxy
 # Note: this command only works on a running bubble node
 #
-ps auxwww | grep /home/mitmproxy/mitmproxy/venv/bin/mitmdump | grep $(cat /home/mitmproxy/mitmproxy_port) | grep -v grep | awk '{print $2}'
+ps auxwww | grep /home/mitmproxy/mitmproxy/venv/bin/mitmdump | grep "$(cat /home/mitmproxy/mitmproxy_port)" | grep -v grep | awk '{print $2}'

bin/pack_bubble

@@ -13,8 +13,8 @@
 #   cloud CloudName  : only pack for CloudName compute cloud, do not pack for all clouds
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${1}" ]] ; then
   IMAGES="node sage"

bin/pack_status

@@ -36,8 +36,8 @@
 # If you pass the 'completed' argument, only the map of cloud->image[] will be printed
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -z "${1}" ]] ; then
   bget me/packer

bin/prep_bubble_jar

@@ -21,7 +21,7 @@
 #
 SCRIPT="${0}"
 SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
-. "${SCRIPT_DIR}/bubble_common"
+. "${SCRIPT_DIR}"/bubble_common
 
 if [[ -n "${DEBUG_BUILD}" && "${DEBUG_BUILD}" == "debug" ]] ; then
   echo "DEBUG_BUILD is set, not doing anything further"

bin/reset_bubble_db

@@ -10,7 +10,7 @@
 #
 SCRIPT="${0}"
 SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
-. "${SCRIPT_DIR}/bubble_common"
+. "${SCRIPT_DIR}"/bubble_common
 
 DEBUG=${1}
 if [[ -n "${DEBUG}" && "${DEBUG}" == "debug" ]] ; then

bin/reset_bubble_full

@@ -8,7 +8,7 @@
 #
 SCRIPT="${0}"
 SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
-. "${SCRIPT_DIR}/bubble_common"
+. "${SCRIPT_DIR}"/bubble_common
 
 SELF_NODE_JSON="${HOME}/self_node.json"
 BUBBLE_VERSIONS_FILE="${HOME}/bubble_versions.properties"

bin/run.sh

@@ -30,8 +30,8 @@
 #
 #
 SCRIPT="${0}"
-SCRIPT_DIR=$(cd $(dirname ${SCRIPT}) && pwd)
-. ${SCRIPT_DIR}/bubble_common
+SCRIPT_DIR="$(cd "$(dirname "${SCRIPT}")" && pwd)"
+. "${SCRIPT_DIR}"/bubble_common
 
 # fail on any command error
 set -e

bubble-server/src/main/java/bubble/main/BubbleMain.java

@@ -21,6 +21,8 @@ import java.util.Map;
 import java.util.TreeSet;
 
 import static org.cobbzilla.util.collection.ArrayUtil.shift;
+import static org.cobbzilla.util.main.BaseMainOptions.LONGOPT_HELP;
+import static org.cobbzilla.util.main.BaseMainOptions.OPT_HELP;
 
 public class BubbleMain {
 
@@ -43,7 +45,11 @@ public class BubbleMain {
 
     public static void main(String[] args) throws Exception {
 
-        if (args.length == 0) die(noCommandProvided());
+        if (args.length == 0 || (
+                args.length == 1 && ( args[0].equals(OPT_HELP) || args[0].equals(LONGOPT_HELP) )
+        )) {
+            die(noCommandProvided());
+        }
 
         SLF4JBridgeHandler.removeHandlersForRootLogger();
         SLF4JBridgeHandler.install();

docs/dev_manual.md

@@ -42,5 +42,8 @@ cd ${HOME} && ln -s .bubble.env .bubble-test.env
 The `.bubble-test.env` file is used by the test suite.
 
 ## What's Next
-Continue reading the [Bubble Developer Guide](dev.md) for information
-on how to update the source code, reset the database, and more.
+Read [Bubble Developer Tasks](dev_tasks.md) to understand how to keep the code
+up to date, run the API server, rebuild the jar, and more.
+
+If you've started the Bubble API already using `run.sh`, and want to launch a Bubble,
+continue with [activation](activation.md).

docs/dev_tasks.md

@@ -3,15 +3,52 @@ Bubble Developer Tasks
 How to update the codebase, how to run the API server, how to reset the database.
 
 ## Updating the Code
-If you want to grab the latest code, and ensure that all git submodules are properly in sync with the main repository, run:
+You can use normal git tools just fine with Bubble. Be aware that the bubble git
+repository makes extensive use of git submodules. So we provide some tools to
+make simple things simple. Everything is still git, there is no magic here.
+
+If you want to grab the latest code and ensure that all git submodules are properly
+in sync with the main repository:
+ * First, ensure that you have no locally modified files (or `git stash` your changes)
+ * Then run:
 ```shell script
 ./bin/git_update_bubble.sh
 ```
-
 This will update and rebuild all submodules, and the main bubble jar file.
 
+## Building
+If you've changed files in `bubble-server/src/`, and you want to see those changes live,
+you'll need to rebuild:
+```shell script
+bbuild
+```
+
+## Rebuilding Utilities
+If you change source files in one of the submodules under `utils`, you'll need to
+rebuild (and `mvn install`) those submodules, **and then** run `bbuild` to incorporate
+the changed libraries into the Bubble jar.
+
+## Rebuilding the Web Site
+If you change files in `bubble-web`, you don't need to run a full `bbuild`.
+Instead you can run the much faster `webpack`.
+
+Run this from the `bubble-web` directory:
+```shell script
+rm -f ./dist/* && webpack
+```
+This will remove all previous site files and have webpack regenerate the HTML/CSS/JS for the
+Bubble web UI.
+
+If you look in `${HOME}/.bubble.env`, you'll see that the `BUBBLE_ASSETS_DIR` variable points
+to `${HOME}/bubble/bubble-web/dist`. Thus, when you run `webpack` to update the files in `dist`,
+the "live" site is updated.
+
 ## Running the API server
-Run the `./bin/run.sh` script to start the Bubble server.
+To start the Bubble server:
+```shell script
+./bin/run.sh
+```
+This will run the server in the foreground. Hit Control-C to stop it.
 
 ## Reset everything
 If you want to "start over", run:
@@ -22,3 +59,8 @@ If you want to "start over", run:
 This will remove local files stored by Bubble, and drop the bubble database.
 
 If you run `./bin/run.sh` again, it will be like running it for the first time.
+
+## Other tools
+There are many other tools in the `bin` directory.
+
+Most tools accept a `-h` / `--help` option and will print usage information.

docs/dev_vagrant.md

@@ -38,8 +38,10 @@ LETSENCRYPT_EMAIL=someone@example.com BUBBLE_PORT=8080 vagrant up
 ```
 
 The first time `vagrant up` runs it will take a long time to complete, since it needs to
-download and build a lot of stuff. For future runs of `vagrant up`, startup times will be
-much faster.
+download and build a lot of stuff. Depending on the speed of your computer and internet,
+it could take anywhere from 5 to 20 or more minutes.
+
+For future runs of `vagrant up`, startup times will be much faster.
 
 When the command completes, you'll have a Vagrant box with the Bubble source code and all
 dependencies fully built and ready to run a local launcher.
@@ -94,5 +96,8 @@ rsync -avzc /vagrant/* /vagrant/.* ${HOME}/bubble/
 ```
 
 ## What's Next
-Continue reading the [Bubble Developer Guide](dev.md) for information
-on how to update the source code, reset the database, and more.
+Read [Bubble Developer Tasks](dev_tasks.md) to understand how to keep the code
+up to date, run the API server, rebuild the jar, and more.
+
+If you've started the Bubble API already using `run.sh`, and want to launch a Bubble,
+continue with [activation](activation.md).