From 86eb3b17491d25f86c602d5ddbbdba839a128707 Mon Sep 17 00:00:00 2001 From: Jonathan Cobb Date: Mon, 23 Nov 2020 12:39:03 -0500 Subject: [PATCH] update docs --- docs/dev.md | 17 ++++++++++ docs/launch-types.md | 74 ++++++++++++++++++++++++++++++++++++++++++++ docs/packer.md | 11 ++----- 3 files changed, 93 insertions(+), 9 deletions(-) create mode 100644 docs/launch-types.md diff --git a/docs/dev.md b/docs/dev.md index d438b96d..d261f99f 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -2,6 +2,8 @@ Bubble Developer Guide ====================== This guide is intended for developers who would like to work directly with the Bubble source code. +For API-level details, see the [the Bubble API](https://github.com/getbubblenow/bubble-docs/blob/master/api/README.md) + # Development Setup These instructions presume you are running a newly setup Ubuntu 20.04 or Mac OS X system. @@ -56,3 +58,18 @@ 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. + +## Next +What to do next depends on what you want to do with Bubble. + +If you've started the Bubble API already using `run.sh`, and want to launch a Bubble, +continue with [activation](activation.md). + +Would you like more guidance on starting the [Local Launcher](local-launcher.md)? + +If all you want to do is launch your own Bubble, starting with +the [Bubble Docker Launcher](docker-launcher.md) is probably faster and easier. + +Or perhaps you are interested in exploring the +[Bubble API](https://github.com/getbubblenow/bubble-docs/blob/master/api/README.md) and +interacting with Bubble programmatically. diff --git a/docs/launch-types.md b/docs/launch-types.md new file mode 100644 index 00000000..acf38566 --- /dev/null +++ b/docs/launch-types.md @@ -0,0 +1,74 @@ +Bubble Launch Types +=================== +There are different ways to launch a Bubble, depending on what you're trying to do. + +First we'll discuss how to set the launch type, then look at what the different options are and what +they mean. + +# Setting the Launch Type +How you set the launch type depends on whether you use the web interface or the [CLI/API](https://github.com/getbubblenow/bubble-docs/blob/master/api/README.md). + +### Via Web UI +Launch Type is called "Bubble Type" in the web interface. + +On the Bubble launch screen, click the "Launch with Advanced Settings" link. +The first drop-down option is "Bubble Type". + +### Via the API +The Launch Type is called `installType` in the Bubble API. When using the API, set the `launchType` property in the JSON object that creates the Bubble. + +# What Makes Launch Types Different? +The two key distinguishing characteristics of each Launch Type are its **Mode** and how it handles **Cloud Services**. + +### Bubble Mode +The mode can be either `sage` or `node`. + +A `sage`, also called a launcher, is a Bubble that launches other Bubbles. +You don't connect devices to a sage/launcher. You just launcher other Bubbles with it. + +A `node`, also often just called a Bubble, is a regular Bubble that acts as a VPN and you connect devices to it. +A Bubble can either delegate cloud services back to the Bubble that launched it (we call this a Bubble in cloud mode), +or it can call cloud services directly (a Bubble in standalone mode). + +The mode is called `installType` in the [API](https://github.com/getbubblenow/bubble-docs/blob/master/api/README.md) + +### Cloud Services +A bubble will either delegate cloud services back to the launcher that created it, +or use the cloud services directly itself. + +If you don't want your cloud credentials stored in your node, use delegated cloud services. + +Alternatively, if you're starting a launcher or don't want cloud services mediated via a launcher, +you'll want your Bubble to call cloud services directly. + +# Launch Types in Detail +Bubble supports the following launch types: + +## Regular + * **Packer Image**: `node` + * **Mode**: `node` (cloud) + * **Cloud Services**: delegated to the `sage` that launched it + * **Scenario**: Launching regular Bubbles from a Remote Launcher + +## Fork Launcher + * **Packer Image**: `sage` + * **Mode**: `sage` + * **Cloud Services**: cloned from launcher, called directly + * **Scenario**: Creating a Remote Launcher from a Local Launcher + +## Fork Bubble + * **Packer Image**: `node` + * **Mode**: `node` (standalone) + * **Cloud Services**: cloned from launcher, called directly + * **Scenario**: Creating a standalone Bubble with no ties to any launcher + +### Local Launchers +A [Local Launcher](local-launcher.md) is a special case, since it bootstraps everything else. + +Nonetheless, using the same bullet points as above can be informative: + +## Local Launcher + * **Packer Image**: none + * **Mode**: `sage` + * **Cloud Services**: supplied during [activation](activation.md), called directly + * **Scenario**: The first step before launching a proper Bubble diff --git a/docs/packer.md b/docs/packer.md index f185ffa2..c908ae8d 100644 --- a/docs/packer.md +++ b/docs/packer.md @@ -21,15 +21,8 @@ A `sage` image is for deploying new Bubbles in Launcher mode. A launcher is call 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. - -### Setting the Launch Type -#### Via Web UI -On the Bubble launch screen, click the "Launch with Advanced Settings" link. -The first drop-down option is "Bubble Type". - -#### Via the API -When using the API, set the `launchType` property in the JSON object that creates the Bubble. +Bubble will automatically use the appropriate image type based on the [Launch Type](launch-types.md) +in effect for each launch. ## Launching a Bubble while Packer Images are Building If you try to launch a Bubble before the required packer image is ready,