update docs

README.md

@@ -5,61 +5,70 @@ Bubble helps you start and manage your own private VPN.
 It also adds tools to this VPN to improve your internet experience by modifying your traffic: to
 remove ads, block malware, and much more.
 
+Visit the [Bubble website](https://getbubblenow.com/) to learn more.
+
+If you're interested in developing on Bubble, see the [Bubble Developer Guide](docs/dev.md).
+
 ## Operating System Support
-Once your Bubble is running, any device can connect to it: Windows, Linux, Mac, iOS, Android; if it supports VPN connections,
-it will probably work just fine.
+Once your Bubble is running, any device can connect to it: Windows, Linux, Mac, iOS, Android;
+if it supports VPN connections, it will probably work just fine.
 
 However, to launch your own Bubble using this software, you will need a Linux machine to run the launcher.
 It *probably* works on MacOS, but it has not been tested and there are likely to be issues. Pull requests are welcome!
 
 If you'd like to enjoy all the benefits of Bubble without going through this hassle, please try out the Bubble launching
-service available on [bubblev.com](https://bubblev.com). Any Bubble you launch from [bubblev.com](https://bubblev.com)
-will also be "yours only" -- all Bubbles disconnect from their launcher during configuration.
+service available on [getbubblenow.com](https://getbubblenow.com/).
+Any Bubble you launch from [getbubblenow.com](https://getbubblenow.com/) will also be "yours only" -- all Bubbles
+disconnect from their launcher during configuration.
 
 ## Getting Started
+The setup instructions below assume you are running Ubuntu 20.04. If you're running another flavor of Linux,
+you can probably figure out how to get things working. If you're running Mac OS X or Windows, things might be
+more difficult.
 
-### Install OpenJDK 11
-Install [Java 11](https://openjdk.java.net/install/) from OpenJDK.
-It will probably be easier to install using an OS package, for example `sudo apt install openjdk-11-jre-headless`
+### Download a Bubble Distribution
+Download and unzip the latest Bubble release:
+ * [ZIP file](https://git.bubblev.org/bubblev/bubble/archive/release/adventure.zip)
+ * [tar.gz archive](https://git.bubblev.org/bubblev/bubble/archive/release/adventure.tar.gz)
 
-### Install PostgreSQL and Redis
-Install [PostgreSQL 10](https://www.postgresql.org/download/) if it is not installed on your system.
-It will probably be easier to install using an OS package, for example `sudo apt install postgresql`
+Unzip or untar the archive that you downloaded.
 
-Install [Redis](https://redis.io/download) if it is not already installed on your system.
-It will probably be easier to install using an OS package, for example `sudo apt install redis`
+### Install System Software
+You'll need to install some software for Bubble to work correctly.
 
-### Configure PostgreSQL
-The Bubble launcher connects to a PostgreSQL database named 'bubble' as the PostgreSQL user 'bubble'.
+Run the `bin/first_time_ubuntu.sh` command.
+This will grab all the submodules and perform an initial build of all components.
 
-If your current OS user account has permissions to create PostgreSQL databases and users, you can skip this step
-since the database and user will be created upon startup.
+You only need to run this command once, ever, on a given system.
+It ensures that the appropriate packages are installed and proper databases and database users exist.
 
-Otherwise, please either:
-  * Update the PostgreSQL `pg_hba.conf` file to allow your current OS user to create databases and DB users, OR
-  * Create a PostgreSQL database named `bubble` and a database user named `bubble`. Set a password for the `bubble` user,
-  and set the environment variable `BUBBLE_PG_PASSWORD` to this password when starting the Bubble launcher.
+`first_time_ubuntu.sh` command uses `apt` commands to install various packages, so Debian (or other Debian-based)
+distributions should work fine. If you are running on a non-Ubuntu system, copy that file to something like:
+                                
+    ./bin/first_time_myoperatingsystem.sh
+                                
+And then edit it such that all the same packages get installed.
+Then submit a pull request and we can add support for your operating system to the main repository.
 
-### Download a Bubble Distribution
-Download and unzip the latest [Bubble Distribution ZIP](https://bubblev.com/download).
+## Deployment Modes
+Bubble runs in three different modes.
+In order to launch and use your own Bubble that you can connect devices to and use,
+you will progress through each of these modes.
 
-### Start the Bubble launcher
-Run the `./bin/run.sh` script to start the Bubble launcher. Once the server is running, it will try to open a browser window
-to continue configuration. It will also print out the URL, so if the browser doesn't start correctly, you can paste this
-into your browser's location bar.
+#### Local Launcher Mode
+In this mode, Bubble runs locally on your machine. You'll setup the various cloud services required to run Bubble,
+and use the Local Launcher to fork a Remote Launcher.
 
-### Activate your local Bubble
-Your Bubble is running locally in a "blank" mode. It needs an initial "root" account and some basic services configured.
+Learn more about setting up [Local Launcher Mode](docs/local-launcher.md)
 
-#### Activate via Web UI
-The browser-based admin UI should be displaying an "Activate" page. Complete the information on this page and submit the
-data. The Bubble Launcher will create an initial "root" account and other basic system configurations. 
+#### Remote Launcher Mode
+In this mode, Bubble is running in the cloud in Launcher Mode, ready to launch new Bubbles that you can use.
+You cannot connect devices to a Bubble in Launcher Mode, you can only use it to launch new Bubbles.
 
-#### Activate via command line
-Copy the file in `config/activation.json`, then edit the file. There are comments in the file to guide you.
-After saving the updated file, run this command:
+Learn more about setting up [Remote Launcher Mode](docs/remote-launcher.md)
 
-   `./bin/bactivate /path/to/activation.json`
+#### Bubble Node Mode
+In this mode, the Bubble has been launched by a Remote Launcher and is a proper Bubble Node.
+You can connect your devices to it and use it as your own private VPN and enhanced internet service.
 
-### Launch a new Bubble!
-Using the web UI, click "Bubbles", select "New Bubble". Fill out and submit the New Bubble form, and your Bubble will be created!
+Learn more about launching a [Bubble Node](docs/launch-node.md)

config/activation.json

@@ -1,6 +1,6 @@
 {
   // name, password and description of the initial admin user
-  "name": "root",
+  "name": "root",    // do not change this, the initial admin user must be named root
   "password": "REPLACE WITH YOUR ROOT PASSWORD",
   "description": "root user",
 
@@ -31,7 +31,7 @@
     "AmazonEC2Driver" : {
       "config": {
         // region must be a valid value from the Regions enum: https://github.com/aws/aws-sdk-java/blob/master/aws-java-sdk-core/src/main/java/com/amazonaws/regions/Regions.java
-        "region": "your_aws_region"
+        "region": "your_aws_region"  // for example: us-east-1
       },
       "credentials" : {
         "AWS_ACCESS_KEY_ID": "your_aws_access_key_id",
@@ -54,13 +54,8 @@
       }
     },
 
-    // Required for TOTP-based authentication. Highly recommended.
-    "TOTPAuthenticator": {},
-
-    // OPTIONAL SERVICES
-    // Comment out any services you have not configured
-
-    // Required for sending emails
+    // You must configure the an SMTP service, it is required to send emails
+    // SendGrid, MailGun, or any other SMTP service should work fine
     "SmtpServer": {
       "config": {
         "tlsEnabled": true
@@ -73,7 +68,10 @@
       }
     },
 
-    // Required for sending SMS messages
+    // Required for TOTP-based authentication. Nothing to configure, just leave this as-is
+    "TOTPAuthenticator": {},
+
+    // Required for sending SMS messages. Currently only Twilio is supported
     "TwilioSms": {
       "credentials": {
         "accountSID": "your_twilio_account_SID",
@@ -83,28 +81,28 @@
       }
     },
 
-    // Required for locale and "nearest compute region" auto-detection
+    // Required for locale and "nearest compute region" auto-detection. Currently only MaxMind is supported.
     "MaxMind": {
       "config": {
-        // these values work for the free GeoLite database. you still have to specify an apiKey
+        // these values work for the free GeoLite database, but you still have to specify an apiKey
         "url": "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=[[apiKey]]&suffix=tar.gz",
         "file": "GeoLite2-City_20[\\\\d]{6}/GeoLite2-City\\\\.mmdb"
       },
       "credentials": {"apiKey": "your_maxmind_api_key"}
     },
 
-    // Required for "nearest compute region" auto-detection
+    // Required for "nearest compute region" auto-detection. Currently only Google GeoCoder is supported.
     "GoogleGeoCoder": {
       "credentials": {"apiKey": "your_google_api_key"}
     },
 
-    // Required for timezone auto-detection
+    // Required for timezone auto-detection. Currently only Google GeoTime is supported.
     "GoogleGeoTime": {
       "credentials": {"apiKey": "your_google_api_key"}
     }
   },
 
-  // the domain that new Bubbles will be launched within
+  // initial domain that new Bubbles will be launched within
   "domain": {
     "publicDns": "Route53Dns or GoDaddyDns",  // name of a DNS provider configured above
     "name": "example.com"  // a domain name that you own, that is managed by the DNS provider named in `publicDns`

docs/dev.md

@@ -1,5 +1,5 @@
-bubble
-======
+Bubble Developer Guide
+======================
 
 # Development Setup
 These instructions presume you are running a newly setup Ubuntu 20.04 system.
@@ -48,5 +48,4 @@ If you want to grab the latest code, and ensure that all git submodules are prop
 This will update and rebuild all submodules, and the main bubble jar file.
 
 ## Running in development
-Assuming you ran the commands above, you can run a test server using the method described in
-the bubble-web [README](https://git.bubblev.org/bubblev/bubble-web/src/branch/master/README.md).
+Run the `bin/run.sh` script to start the Bubble server.

docs/launch-node.md

@@ -0,0 +1,40 @@
+# Bubble Node Mode
+A Bubble in Node Mode is a proper Bubble that allows you to connect your devices to it, and manages network traffic
+on behalf of those devices.
+
+Launching a Bubble in Node Mode requires a Bubble in Remote Launcher Mode. If you don't have
+a Bubble in Remote Launcher Mode, go back and follow the [Remote Launcher Mode instructions](remote-launcher.md).
+
+## Create a user
+On your Remote Launcher, use the `/register` URL to create a new user account.
+
+It is highly recommended to launch new Bubbles using a regular user account, and not your Remote Launcher root account.
+
+## Verify user
+After you create a user, the Remote Launcher will send an email with a verification link.
+Click the link in the email to verify your new account.
+
+## Launch Bubble
+After you click the verification link, you should see a "Launch Bubble" screen.
+
+Choose your configuration options, then click the "Launch Your Bubble!" button kick things off.
+
+The screen will refresh and show a progress meter.
+
+While your Bubble is launching, take a moment to
+[install the Bubble Native app](https://support.getbubblenow.com/hc/en-us/articles/360050801634-Connect-a-device-to-your-Bubble)
+on each device you plan on connecting to your Bubble.
+
+When your Bubble finishes launching, it will show a "Connect to Bubble" button. Click this and you'll be connected
+to your Bubble Node.
+
+## Connect Devices
+[Install the Bubble Native app](https://support.getbubblenow.com/hc/en-us/articles/360050801634-Connect-a-device-to-your-Bubble)
+on each device you plan on connecting to your Bubble.
+
+Start the app. At the bottom of the login screen, you should see "Running your own Bubble? Set Launcher".
+
+Click or tap "Set Launcher" and enter the hostname of your Remote Launcher.
+
+Then fill out the "Email" and "Password" fields, and click or tap the "Sign In" button.
+Your Bubble should automatically connect and configure the device. If it does not, click or tap the "Connect" button.

docs/local-launcher.md

@@ -0,0 +1,29 @@
+# Bubble Local Launcher Mode
+A Bubble in Local Launcher Mode is the starting point for standing up a Bubble in
+[Remote Launcher Mode](remote-launcher.md), which you can then use to launch proper Bubbles
+in [Bubble Node Mode](launch-node.md).
+
+### Run Bubble
+Run the `./bin/run.sh` script on your local machine to start Bubble in Local Launcher mode.
+Once the server is running, it will try to open a browser window to continue configuration.
+It will also print out the URL, so if the browser doesn't start correctly, you can paste this
+into your browser's location bar.
+
+### Activation
+Your Bubble is running locally in a "blank" mode. It needs an initial "root" account and some basic services configured.
+
+#### Activate via Web UI
+The browser-based admin UI should be displaying an "Activate" page. Complete the information on this page and submit the
+data. The Bubble Launcher will create an initial "root" account and other basic system configurations. 
+
+#### Activate via command line
+Copy the file in `config/activation.json`, then edit the file. There are comments in the file to guide you.
+After saving the updated file, run this command:
+
+   `./bin/bactivate /path/to/activation.json`
+
+After running the above, 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.
+
+You are now read to Launch Bubble in [Remote Launcher Mode](remote-launcher.md)

docs/remote-launcher.md

@@ -0,0 +1,32 @@
+# Bubble Remote Launcher Mode
+You must already have a Bubble running in [Local Launcher Mode](local-launcher.md) to proceed.
+
+## Start Bubble
+If your Bubble is not already running on your local system, start it by running `./bin/run.sh`
+
+## Log In
+When your local Bubble finishes launching, it should open a web page. If you a page with the title "Activation",
+then your Bubble still needs to be activated. Read about activation in the [Local Launcher Mode](local-launcher.md) instructions.
+
+If you see a login screen, you should be able to log in as the admin user using the email
+address `root@local.local` and the password from your `activation.json` file.
+
+## Fork a Remote Launcher
+After you log in, you should see a "Launch Bubble" screen.
+
+In the "Bubble Type" drop-down box, choose "Fork".
+
+In the "Fork Host" field, enter the fully-qualified domain name (FQDN) that the Bubble will be known as.
+
+In the "Plan" field, it is recommended to choose the highest-level plan. The Remote Launcher requires a decent amount
+of memory and CPU.
+
+In the "Domain" field, choose the domain that corresponds to the FQDN you entered in the "Fork Host" field.
+
+Configure the remaining fields as you desire. When you're ready, click the "Launch Your Bubble!" button.
+
+The screen will refresh and show a progress meter.
+When your Bubble finishes launching, it will show a "Connect to Bubble" button. Click this and you'll be connected
+to your Remote Launcher.
+
+You are now ready to [Launch a Bubble](launch-node.md)