Get Started

Outcomes

The outcome of this getting started section is to download, install and run Streambed services including a “hello world” style of service running - all within 10 minutes. We want you to see enough of Streambed to then be prepared to invest more of your valuable time.

Prerequisities

The prerequisites for getting started are an internet connection and having Docker installed and running. Docker allows us to easily run applications and avoid any complex installation requirements.

For macOS and Windows, please ensure that Docker is running. This done by running a Docker application. If you need further information, please consult the Docker installation documentation for your platform.

On macOS, we also recommend that you install our packages using Homebrew. Please take the Windows option if you’d prefer to install our packages outside of Homebrew.

Lastly, you should be familiar with your computer’s terminal window, or at least how to open it and copy/paste commands from here.

An overview of the steps

The steps for getting started are as follows:

1. Download our command line tools - this is a single, small download
2. Run what we call the “sandbox” - an environment that stands up the core Streambed services on your machine, running within Docker containers
3. Open our Control Center - this is a web app that displays sensor data in real-time

Let’s go!

1. Download the command line tools

Please select the type of installation and follow the instructions.

Debian/Ubuntu

# Setup Repository
wget -qO - https://repositories.streambed.io/public.key | \
  sudo apt-key add - && \
  echo "deb [arch=amd64] https://repositories.streambed.io/apt/streambed stable main" | \
  sudo tee /etc/apt/sources.list.d/streambed.list && \
  sudo apt-get install apt-transport-https -y && \
  sudo apt-get update
# Install the streambed-cli
sudo apt-get && sudo apt-get install streambed-cli

RedHat/CentOS/Fedora

# Setup Repository
sudo tee /etc/yum.repos.d/streambed.repo << EOT
[streambed]
name=streambed
baseurl=https://repositories.streambed.io/yum
gpgcheck=0
enabled=1
EOT
# Install the streambed-cli
sudo yum install streambed-cli

macOS

# Setup Repository
brew tap streambed/repository https://github.com/streambed/homebrew-repository
# Install the streambed-cli
brew install streambed/repository/streambed-cli

Windows

Download the latest win-<arch>.zip file and extract it to a directory on your PATH.
You can find the files here: https://repositories.streambed.io/packages/streambed-cli/

Three commands are now at your disposal: sandbox, streambed and lora. Let’s type one to verify that the installation worked:

sandbox --feature farm

You’ll then get a bit of output ending with:

# This is a Docker Compose file.
# Usage:
#   Start:  sandbox --feature farm | docker-compose -p xdp-sandbox -f - up
#   Stop:   sandbox --feature farm | docker-compose -p xdp-sandbox -f - down

The sandbox command generates a file that can be used as input to docker-compose. A major theme of Streambed is to leverage technologies and their strong communities. docker-compose is a case-in-point and may already be familiar to you. What it does is manage a number of Docker applications which ends up saving you a lot of typing and error.

The --feature farm tells the sandbox command to generate all that is required to start a demonstration containing a live dashboard for a farm. The dashboard visualizes randomly generated data for electric fence and water level readings.

2. Run the “sandbox”

To run the sandbox:

sandbox --feature farm | docker-compose -p xdp-sandbox -f - up

The sandbox takes a few moments when first run as various “images” that support Streambed have to be downloaded. Once started, you’ll see a welcome message along with the following:

provision-iox-sss_1               | CLI                : `streambed -h`, `lora -h`
provision-iox-sss_1               | Credentials        :
provision-iox-sss_1               |   Username         : admin
provision-iox-sss_1               |   Password         : password
provision-iox-sss_1               | Control Center     : https://localhost:9870/
provision-iox-sss_1               | MQTT               : `docker logs -f $(docker ps -q -f name=streambed-mqtt)`
provision-iox-sss_1               | Features           :
provision-iox-sss_1               |   Farm             : See Control Center

These greeting messages help us understand how to navigate the sandbox environment. Note that some of the information presented above may be different for you.

3. Open our Control Center

You’ll see in the greeting that we can access the Control Center via https://localhost:9870/. Copy the corresponding link presented in the greeting on your machine paste it into your browser and enter the admin and password values when prompted for credentials. You should then see an image like the following, and the readings from the sensors being updated every ten seconds:

Note the latest readings from the water and electric fences are updated in realtime, and a historical view is provided that lets you see the readings over the past two hours, one day, one week, and one month.

It’s a wrap!

That’s it, you’ve stood up a Streambed environment on your machine!

For the curious, from another terminal window you can see exactly how many services have started up by issuing the following command:

docker ps

To finish up, use Ctrl-C to quit out of the sandbox and then issue the following command to tidy up (it is the same command as before, only with a down on the end instead of up):

sandbox --feature farm | docker-compose -p xdp-sandbox -f - down

Where to next?

If you’re a developer then you’ll probably want to visit the Developer documentation where you can also get an overview of the architecture. If you’re focused more on installing a Streambed environment for production then please head on over to the Operations documentation.