add packer docs

docs/activation.md

@@ -30,13 +30,6 @@ To activate your Local Launcher Bubble, run this command:
 
 ## Activation Notes
 
-### Admin User Name
-Do not change the name of the initial admin user, or some things might not work correctly. 
- * For web-based activation, this is the `Username` field near the top.
- * For JSON-based activation, this is the `name` JSON element.
-
-The username of the initial admin user should always be `root`.
-
 ### Required Clouds
 You must define at least one cloud provider for each of these categories:
   * DNS (Amazon Route53 or GoDaddy DNS)
@@ -53,7 +46,18 @@ The DNS provider for this domain must be specified.
  * For web-based activation, this is the `DNS for this Domain` field at the bottom.
  * For JSON-based activation, this is the `domain.publicDns` JSON element.
 
-## After Activating
+## Behind the Scenes
+In the background, the Bubble launcher is building packer images for the compute cloud(s) defined during activation.
+
+This process usually takes about 20 minutes but can take up to an hour, depending on how many compute clouds you have
+and how fast the internet is.
+
+[Learn more about Packer images](packer.md).
+
+## Sign In to Admin Account
 After performing activation, refresh the web page that opened when the server started. You should see a login page.
 
 You can now login as the admin user using the email address `root@local.local` and the password from your `activation.json` file.
+
+## Launch Time
+Activation is complete! Ready to [launch a Bubble](launch-node.md)?

docs/packer.md

@@ -0,0 +1,63 @@
+# Bubble Packer Images
+A [packer image](https://packer.io) is way to initialize a new cloud system with an operating system and
+software and files pre-installed. This is an oversimplified explanation but will suffice for our current needs.
+ 
+Before packer images, we launched Bubbles onto "blank" Ubuntu 20.04 systems and then did
+tons of installation and configuration. It took 20+ minutes to launch a new Bubble.
+
+We decided we could do better. Packer allows us to create Ubuntu 20.04 images that already have 
+PostgreSQL, Redis and nginx installed and configured, and lots more.
+
+Launching a Bubble is now faster (usually 10 minutes or less) because all the standard software
+and configs are already present on the packer image that each launch starts with.
+
+We can make it even faster, but getting a new Bubble launched in under 10 minutes is a real accomplishment,
+and Packer makes it possible. 
+
+## Image Types
+There are two types of packer images: `sage` and `node`
+
+A `sage` image is for deploying new Bubbles in Launcher mode. A launcher is called a `sage` in the Bubble API.
+
+A `node` image is for deploying new Bubbles in Node mode. A regular Bubble that acts as a VPN for devices is called a `node` in the Bubble API.
+
+Bubble will automatically use the appropriate image type based on the Launch Type.
+
+To set the Launch Type: on the Bubble launch screen, click the "Launch with Advanced Settings" link.
+
+When using the API, set the `launchType` property in the JSON request that creates the Bubble. 
+
+## Launching a Bubble while Packer Images are Building
+If you try to launch a Bubble before the required packer image is ready, your Bubble launch will detect that the image
+is in the process of being built, and wait until it is ready before trying to use them.
+
+## Image Validity
+The packer images are tied to a specific Bubble version. As long as the Bubble API launcher can find packer images
+that match its version, it will be able to launch Bubbles.
+
+When your Bubble is upgraded, its version changes, so the old packer images are no longer valid.
+
+Your Bubble will automatically build new images the next time a Bubble is launched.
+
+If you'd prefer not to add a 20 minute delay (as packer images are built) to the next Bubble launch, you
+can manually rebuild the images after upgrading your Bubble server. See below.
+
+## Manually Rebuilding Packer Images
+To ensure that all required packer images exist (build them if needed):
+ 
+    ./bin/pack_bubble
+
+For more information, see:
+
+    ./bin/pack_bubble --help
+
+Note: to use the `bin` tools, define environment variables `BUBBLE_USER`, `BUBBLE_PASS`, and `BUBBLE_API`
+appropriately for your Bubble. For example:
+
+    export BUBBLE_USER=user@example.com
+    export BUBBLE_PASSWORD=password
+    export BUBBLE_API=https://bubble.example.com/api   # deployed launcher
+    export BUBBLE_API=http://127.0.0.1:8090/api        # local launcher
+
+    ./bin/pack_bubble
+