From c40546e687b3e7cddb4ebf9760dea5df356289c8 Mon Sep 17 00:00:00 2001 From: Jonathan Cobb Date: Sun, 15 Nov 2020 13:15:12 -0500 Subject: [PATCH] update docs to include docker launcher --- README.md | 40 ++----------- docker/launcher.sh | 130 +++++++++++++++++++++++++++++++++++----- docs/activation.md | 27 +++++++++ docs/docker-launcher.md | 37 ++++++++++++ docs/local-launcher.md | 21 +------ docs/run-binary.md | 43 +++++++++++++ 6 files changed, 232 insertions(+), 66 deletions(-) create mode 100644 docs/activation.md create mode 100644 docs/docker-launcher.md create mode 100644 docs/run-binary.md diff --git a/README.md b/README.md index 76d64137..710155fd 100644 --- a/README.md +++ b/README.md @@ -19,45 +19,15 @@ It *probably* works on MacOS, but it has not been tested and there are likely to ## The Easy Path 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 [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. - -### Download a Bubble Distribution -Download the [latest Bubble release](https://jenkins.bubblev.org/public/releases/bubble/latest/bubble.zip) - -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. Run: - - ./bin/first_time_ubuntu.sh - -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. -It ensures that the appropriate packages are installed and proper databases and database users exist. - -`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 a different OS or distribution, 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. +The [Bubble Docker Launcher](docs/docker-launcher.md) is the fastest way to get started using Bubble. +If you're feeling more adventurous, you can also [run a binary distribution](docs/run-binary.md), or [build Bubble from source](docs/dev.md). + ## Deployment 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 @@ -67,6 +37,8 @@ directly from the Local Launcher. 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 start a Remote Launcher or a Bubble Node. +This is the mode that the [Bubble Docker Launcher](docs/docker-launcher.md) runs. + Learn more about setting up [Local Launcher Mode](docs/local-launcher.md) #### Remote Launcher Mode diff --git a/docker/launcher.sh b/docker/launcher.sh index 45fe2727..712972b8 100644 --- a/docker/launcher.sh +++ b/docker/launcher.sh @@ -30,18 +30,44 @@ function get_bubble_tag() { echo -n "getbubble/launcher:${VERSION}" } -function setup_docker_linux() { +function setup_docker_debian() { # Ensure apt is up to date sudo apt update -y + # Remove obsolete packages + sudo apt-get remove docker docker-engine docker.io containerd runc + # Ensure apt can install packages over https - sudo apt install -y apt-transport-https ca-certificates curl software-properties-common + sudo apt install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common + + # Install docker GPG key + curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - + + # Add docker repo + sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" + + # Refresh apt after adding repo + sudo apt update -y + + # Install docker + sudo apt install -y docker-ce docker-ce-cli containerd.io +} + +function setup_docker_ubuntu() { + # Ensure apt is up to date + sudo apt update -y + + # Remove obsolete packages + sudo apt-get remove docker docker-engine docker.io containerd runc - # Install Docker GPG key + # Ensure apt can install packages over https + sudo apt install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common + + # Install docker GPG key curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - - # Add Docker apt repo - sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable" + # Add docker repo + sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" # Refresh apt after adding repo sudo apt update -y @@ -50,6 +76,72 @@ function setup_docker_linux() { sudo apt install -y docker-ce } +function setup_docker_centos_dnf() { + # Update dnf + sudo dnf update -y --nobest + + # Add docker repo + sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo + + # Refresh dnf after adding repo + sudo dnf update -y --nobest + + # Install docker + sudo dnf install -y docker-ce --best --allowerasing + + # Start docker + sudo systemctl start docker +} + +function setup_docker_centos_yum() { + # Remove obsolete docker packages + sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine + + # Add docker repo + sudo yum install -y yum-utils + sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo + + # Install docker + sudo yum install docker-ce docker-ce-cli containerd.io + + # Start docker + sudo systemctl start docker +} + +function setup_docker_fedora_dnf() { + # Update dnf + sudo dnf update -y --nobest + + # Install docker + sudo dnf install -y docker-ce + + # Start docker + sudo systemctl start docker +} + +function setup_docker_linux() { + DISTRO="$(cat /etc/os-release | grep "^NAME" | awk -F '=' '{print $2}' | tr -d '"')" + if [[ $(echo -n ${DISTRO} | grep -c Debian | tr -d ' ') -gt 0 ]] ; then + setup_docker_debian + elif [[ $(echo -n ${DISTRO} | grep -c Ubuntu | tr -d ' ') -gt 0 ]] ; then + setup_docker_ubuntu + elif [[ $(echo -n ${DISTRO} | grep -c CentOS | tr -d ' ') -gt 0 ]] ; then + if [[ ! -z "$(which dnf)" ]] ; then + setup_docker_centos_dnf + elif [[ ! -z "$(which yum)" ]] ; then + setup_docker_centos_yum + else + die "Neither dnf nor yum found, cannot install on CentOS. +Please install docker manually from https://docker.io/" + fi + elif [[ $(echo -n ${DISTRO} | grep -c Fedora | tr -d ' ') -gt 0 ]] ; then + setup_docker_fedora_dnf + else + die "Automatic docker installation for ${DISTRO} is not yet supported +Please install docker manually from https://docker.io/" + fi +} + function setup_docker_macosx() { if [[ -z "$(which brew)" ]] ; then die "Homebrew not installed (brew command not found). Install homebrew by running: @@ -62,25 +154,35 @@ function setup_docker_macosx() { } function setup_docker() { - PLATFORM="$(uname -s)" - if [[ -z "${PLATFORM}" ]] ; then - die "'uname -a command' returned empty string!" - fi + echo "Installing docker via sudo ..." + if [[ $(whoami) != "root" ]] ; then + echo "Note: you may need to enter your password (for Linux user $(whoami)) to enable sudo commands" + fi - if [[ -z "$(which docker)" ]] ; then - echo "docker command not found" - echo "Installing docker via sudo (you may need to enter your password) ..." if [[ "${PLATFORM}" == "Linux" ]] ; then setup_docker_linux + elif [[ "${PLATFORM}" == "Darwin" ]] ; then setup_docker_macosx eval "$(docker-machine env default)" + docker-machine start default + else die "Don't know how to install docker on ${PLATFORM}" fi +} + +function run_launcher() { + PLATFORM="$(uname -s)" + if [[ -z "${PLATFORM}" ]] ; then + die "'uname -s' returned empty string!" + fi + + if [[ -z "$(which docker)" ]] ; then + setup_docker fi - # Determine bubble docker tag based on meta props bubble version + # Determine bubble docker tag BUBBLE_TAG=$(get_bubble_tag) # Pull bubble docker image @@ -90,4 +192,4 @@ function setup_docker() { docker run -p 8090:8090 -t ${BUBBLE_TAG} } -setup_docker +run_launcher diff --git a/docs/activation.md b/docs/activation.md new file mode 100644 index 00000000..44f52c92 --- /dev/null +++ b/docs/activation.md @@ -0,0 +1,27 @@ +# Bubble Activation +The very first time Bubble runs it has a blank database, nothing has been defined. + +This is a Bubble that is awaiting activation. + +Activation defines the initial data required to run a Bubble launcher. This includes the initial admin password, +cloud services, and DNS domains. + +## Cloud Accounts +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 +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 +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: + + ./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. diff --git a/docs/docker-launcher.md b/docs/docker-launcher.md new file mode 100644 index 00000000..93794514 --- /dev/null +++ b/docs/docker-launcher.md @@ -0,0 +1,37 @@ +# Bubble Docker Launcher + +The Bubble Docker Launcher makes it easy to run a Bubble launcher. + +You can use the launcher to then start Bubbles that you can use. + +## Automatic Setup +If you're running Linux or Mac OS X, try the automatic setup script first. +This script will automatically install docker, pull the Bubble docker image and run it. + + /bin/bash -c "$(curl -sL https://git.bubblev.org/bubblev/bubble/raw/branch/master/docker/launcher.sh)" + +If the script cannot install docker, please [install Docker manually](https://docs.docker.com/engine/install/) +and then re-run the above command. + +## Manual Setup +If you're on Windows or are if you already have Docker installed and are comfortable using it directly, +you can run the Bubble Docker Launcher via: + + BUBBLE_RELEASE_URL="https://jenkins.bubblev.org/public/releases/bubble/latest.txt" + VERSION="$(curl -s ${BUBBLE_RELEASE_URL} | awk -F '_' '{print $2}' | awk -F '.' '{print $1"."$2"."$3}')" + BUBBLE_TAG="getbubble/launcher:${VERSION}" + + docker pull ${BUBBLE_TAG} + docker run -p 8090:8090 -t ${BUBBLE_TAG} + +## Activation +Upon successful startup, the bubble launcher will be listening on port 8090 + +Your Bubble is running locally in a "blank" mode. It needs an initial "root" account and some basic services configured. + +Open http://127.0.0.1:8090/ in a web browser to continue with activation. + +Follow the [Bubble Activation](activation.md) instructions to configure your Bubble. + +## Launch a Bubble! +Once your Bubble launcher has been activated, you can [launch a Bubble](launch-node-from-local.md)! diff --git a/docs/local-launcher.md b/docs/local-launcher.md index 8f1aa0dc..b5bc528e 100644 --- a/docs/local-launcher.md +++ b/docs/local-launcher.md @@ -12,26 +12,11 @@ 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. -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 -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 -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: - - ./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. +Follow the [Bubble Activation](activation.md) instructions to configure your Bubble. ### Resetting everything -If you want to "start over", run: +If you want undo activation and "start over" with a blank Bubble: first, if your local bubble is still running, stop it. +Then, run: ./bin/reset_bubble_full diff --git a/docs/run-binary.md b/docs/run-binary.md new file mode 100644 index 00000000..26e3cf63 --- /dev/null +++ b/docs/run-binary.md @@ -0,0 +1,43 @@ +# Run Bubble from a Binary Distribution +The setup instructions below assume you are running Ubuntu 20.04 or Mac OS X. + +If you're running another flavor of Linux, you can probably figure out how to get things working. + +If you're running Windows, things might be more difficult. + +## Download a Bubble Distribution +Download the [latest Bubble release](https://jenkins.bubblev.org/public/releases/bubble/latest/bubble.zip) + +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. + +For Ubuntu systems, run: + + ./bin/first_time_ubuntu.sh + +For Mac OS X systems, run: + + ./bin/first_time_macosx.sh + +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. + +If you are running a different OS or distribution, copy `first_time_ubuntu.sh` to something like: + + ./bin/first_time_myoperatingsystem.sh + +Then edit it such that all the same packages get installed. + +Submit a pull request, and we'll add support for your operating system to the main repository. + +## \ No newline at end of file