diff --git a/README.md b/README.md index 7701573a..76d64137 100644 --- a/README.md +++ b/README.md @@ -28,16 +28,23 @@ you can probably figure out how to get things working. If you're running Mac OS more difficult. ### 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) +Download the [latest Bubble release](https://jenkins.bubblev.org/public/releases/bubble/latest/bubble.zip) -Unzip or untar the archive that you downloaded. +Open a command-line terminal. + +Unzip the file that you downloaded: + + unzip bubble.zip + +Change directories into the directory containing the files that were unzipped: + + cd bubble-Adventure_1.x.x # replace `Adventure_1.x.x` with the version that you downloaded ### Install System Software -You'll need to install some software for Bubble to work correctly. +You'll need to install some software for Bubble to work correctly. Run: + + ./bin/first_time_ubuntu.sh -Run the `bin/first_time_ubuntu.sh` command. This will grab all the submodules and perform an initial build of all components. You only need to run this command once, ever, on a given system. @@ -51,23 +58,14 @@ distributions should work fine. If you are running a different OS or distributio 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. -### Build -Before running Bubble, you need to build it. Run: - - ./bin/first_time_setup.sh - -This will grab all the submodules and perform an initial build of all components. - -This will take a while to complete, please be patient. - ## 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. +Bubble runs in three different modes. You'll at least need to run a Local Launcher first, then +decide if you want to use a Remote Launcher to manage multiple Bubble nodes, or just launch a single Bubble +directly from the Local Launcher. #### 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. +and use the Local Launcher to start a Remote Launcher or a Bubble Node. Learn more about setting up [Local Launcher Mode](docs/local-launcher.md) @@ -78,7 +76,7 @@ You cannot connect devices to a Bubble in Launcher Mode, you can only use it to Learn more about setting up [Remote Launcher Mode](docs/remote-launcher.md) #### Bubble Node Mode -In this mode, the Bubble has been launched by a Remote Launcher and is a proper Bubble Node. +In this mode, the Bubble has been launched by a Local Launcher or 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. Learn more about launching a [Bubble Node](docs/launch-node.md) diff --git a/bin/build_dist b/bin/build_dist index db65f5da..70d0c238 100755 --- a/bin/build_dist +++ b/bin/build_dist @@ -78,6 +78,7 @@ if [[ ! -z "${BUBBLE_DIST_HOME}" ]] ; then if [[ ${IS_DEV} -eq 0 ]] ; then cd ${BUBBLE_DIST_TOP} && rm -f latest && ln -sf ${BUBBLE_VERSION} latest echo "${BUBBLE_VERSION}" > latest.txt + cd ${BUBBLE_DIST_DIR} && ln -s "$(basename ${BUBBLE_DIST})" bubble.zip && ln -s "$(basename ${BUBBLE_DIST}).sha" bubble.zip.sha256 fi echo "Published release: ${BUBBLE_DIST}" fi diff --git a/docs/dev.md b/docs/dev.md index 5c0cdc22..8af03df0 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -5,11 +5,19 @@ Bubble Developer Guide These instructions presume you are running a newly setup Ubuntu 20.04 system. Either the Ubuntu Server or Desktop distribution will work. +Other Debian-based systems will probably also work fine. + +See below for other Linux distributions and other operating systems. + ## First-Time System Setup +You'll need to install some software for Bubble to work correctly. + After you clone this repository, run: ./bin/first_time_ubuntu.sh +This runs some `apt` commands to install various bits of software needed to run Bubble. + If you are running on a non-Ubuntu system, copy that file to something like: ./bin/first_time_myoperatingsystem.sh diff --git a/docs/launch-node-from-local.md b/docs/launch-node-from-local.md new file mode 100644 index 00000000..2b67bfc5 --- /dev/null +++ b/docs/launch-node-from-local.md @@ -0,0 +1,32 @@ +# Launching a Bubble from a Local Launcher +These instructions assume you have already set up a [Local Launcher](local-launcher.md). + +## Login +Login to your Local Launcher using the root admin account that was created during activation. + +Because the login field must be an email address, use the special email address `root@local.local` to login +with the admin account. + +## Launch Bubble +You should see a "Launch Bubble" screen. + +In the "Bubble Type" drop-down, choose "Fork Bubble" + +Choose your configuration options, then click the "Launch Your Bubble!" button kick things off. + +The screen will refresh and show a progress meter. A typical launch will take about 10 minutes. + +## Your Very First Bubble +The very first Bubble you launch will build a [Packer](https://packer.io) image that will be used for this and +subsequent launches. + +This process adds about 20-25 minutes to the launch process. This only happens the first time you launch a Bubble. +Later launches can skip this step, because Bubble will detect that the packer image already exists. + +## Install Bubble Apps +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. diff --git a/docs/launch-node-from-remote.md b/docs/launch-node-from-remote.md new file mode 100644 index 00000000..fea1860b --- /dev/null +++ b/docs/launch-node-from-remote.md @@ -0,0 +1,35 @@ +# Launching a Bubble from a Remote Launcher +These instructions assume you have already set up a [Remote Launcher](remote-launcher.md). + +## Create a user +Click the "Sign Up" button in the header to create a new user account. + +Note: You *could* sign in using the root account and launch a Bubble from there, but this is discouraged for security reasons. +It is *highly recommended* to launch new Bubbles using a regular user account, and not your Remote Launcher root account. +You should use the root account on the Remote Launcher only to manage the system itself. + +## 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. A typical launch will take about 10 minutes. + +## Your Very First Bubble +The very first Bubble you launch will build a [Packer](https://packer.io) image that will be used for this and +subsequent launches. + +This process adds about 20-25 minutes to the launch process. This only happens the first time you launch a Bubble. +Later launches can skip this step, because Bubble will detect that the packer image already exists. + +## Install Bubble Apps +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. diff --git a/docs/launch-node.md b/docs/launch-node.md index 77c44c88..439e3db5 100644 --- a/docs/launch-node.md +++ b/docs/launch-node.md @@ -2,35 +2,17 @@ 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). +Launching a Bubble in Node Mode requires a Bubble in Local or Remote Launcher Mode. If you don't have +a Bubble in Local or Remote Launcher Mode, go back and follow the [Local Launcher Mode instructions](local-launcher.md) +and/or the [Remote Launcher Mode instructions](remote-launcher.md). -## Create a user -Load your Remote Launcher's home page in a web browser. +Load your Launcher's home page in a web browser. -Click the "Sign Up" button in the header to create a new user account. +## From a Remote Launcher +If you're launching from a [Remote Launcher](remote-launcher.md), follow [these instructions](launch-node-from-remote.md) -Note: You *could* sign in using the root account and launch a Bubble from there, but this is discouraged for security reasons. -It is *highly recommended* to launch new Bubbles using a regular user account, and not your Remote Launcher root account. -You should use the root account on the Remote Launcher only to manage the system itself. - -## 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. +## From a Local Launcher +If you're launching from a [Local Launcher](local-launcher.md), follow [these instructions](launch-node-from-local.md) ## Connect Devices [Install the Bubble Native app](https://support.getbubblenow.com/hc/en-us/articles/360050801634-Connect-a-device-to-your-Bubble) @@ -38,7 +20,7 @@ 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. +Click or tap "Set Launcher" and enter the hostname of your new Bubble Node. 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. diff --git a/docs/local-launcher.md b/docs/local-launcher.md index df7f7e60..53035e89 100644 --- a/docs/local-launcher.md +++ b/docs/local-launcher.md @@ -3,23 +3,23 @@ A Bubble in Local Launcher Mode is the starting point for standing up a Bubble i [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 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 +## Activation Your Bubble is running locally in a "blank" mode. It needs an initial "root" account and some basic services configured. In order to activate your Local Launcher, you'll need accounts and/or API keys from several cloud providers. Have these account credentials handy. Be prepared to sign up for new accounts where needed. -#### Activate via Web UI +### 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 +### Activate via command line Make a copy of the file `config/activation.json` and edit the copy. There are comments in the file to guide you. To activate your Local Launcher Bubble, run this command: @@ -30,4 +30,6 @@ After running the above, refresh the web page that opened when the server starte 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) +## Next Steps +You are now read to launch a new Bubble in [Bubble Mode](launch-node.md), or +a Remote Launcher via [Remote Launcher Mode](remote-launcher.md) diff --git a/docs/remote-launcher.md b/docs/remote-launcher.md index 9abe7b4b..02540f4c 100644 --- a/docs/remote-launcher.md +++ b/docs/remote-launcher.md @@ -15,7 +15,7 @@ address `root@local.local` and the password from your `activation.json` file. After you log in, you should see a "Launch Bubble" screen. If you don't see this screen, click the "My Bubble" link in the header. -In the "Bubble Type" drop-down box, choose "Fork". +In the "Bubble Type" drop-down box, choose "Fork Launcher". In the "Fork Host" field, enter the fully-qualified domain name (FQDN) that the Bubble will be known as. @@ -26,8 +26,17 @@ In the "Domain" field, choose the domain that corresponds to the FQDN you entere 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. +The screen will refresh and show a progress meter. A typical launch will take about 10 minutes. + +## Your Very Remote Launcher +The very first Remote Launcher you launch will build a [Packer](https://packer.io) image that will be used for this and +subsequent launches. + +This process adds about 20-25 minutes to the launch process. This only happens the first time you launch a Remote Launcher. +Later launches can skip this step, because Bubble will detect that the packer image already exists. + +## Next Steps 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) +You are now ready to [Launch a Bubble](launch-node.md) from the Remote Launcher diff --git a/utils/cobbzilla-utils b/utils/cobbzilla-utils index fab2bdaf..0de14792 160000 --- a/utils/cobbzilla-utils +++ b/utils/cobbzilla-utils @@ -1 +1 @@ -Subproject commit fab2bdafe756fc53ff80b58171fb9000846bf0ef +Subproject commit 0de14792b3041723e1c506653b4ef90883849552