Installation for Ubuntu

Installation Instructions for Ubuntu

The following instructions are for Ubuntu 16.04 LTS.

StreamMachine is built using Node.js and has 3 possible running modes:

• standalone
• master
• slave

Both standalone and master/slave modes can be run with or without Redis to store the configuration.

Setting up a common StreamMachine environment

Start with a fully updated environment:

apt-get update
apt-get upgrade
apt-get install -y aptitude
aptitude install -y build-essential git

We'll need Node.js, npm, git command:

curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo aptitude install -y nodejs

Let's now deploy the current StreamMachine master branch from git under /srv:

cd /srv
git clone https://github.com/mediainbox/StreamMachine.git

Make sure you're running the master branch:

# git branch
* master

Install the dependencies:

cd /srv/StreamMachine
npm install

Create a folder to store the logs. If you want to use a dedicated user, chown the folder appropriately.

mkdir -p /var/log/streammachine

Getting started in standalone mode

Here's a simple configuration file for a standalone mode (adapt ports, names and credentials as required):

{
  "port": 8001,
  "source_port": 8002,
  "log": {
    "stdout": true
  },
  "streams": {
    "test": {
      "key": "test",
      "root_route": true,
      "format": "mp3",
      "seconds": 3600,
      "metaTitle": "Testing",
      "host": "localhost",
      "source_password": "testing"
    }
  }
}

It's basically:

• configuring a "test" stream in mp3 with a "testing" password
• listening on TCP/8002 for incoming audio (master)
• listening on TCP/8001 for streaming clients (HLS, icecast, raw...) (slave)
• logging on stdout everything

Now launch manually StreamMachine with the above configuration file:

./streammachine-cmd --config ./config/standalone.json

You can now broadcast to the server's IP on port 8002 with corresponding credentials, and listen on port 8001 with your player:

• http://a.b.c.d:8001/test for icecast
• http://a.b.c.d.:8001/test.m3u8 for HLS
• A playlist is available at http://a.b.c.d:8001/test.pls

Note that navigating over to http://a.b.c.d:8001/index.html should display "OK" if everything goes well.

Getting started in Master/Slave mode

The master does 3 things:

• it is the entry point for the audio source (Nicecast, Airtime, whatever you're using)
• it serves and operates the API
• sends master stream to the slave

The slave is where clients connect to listen to the stream.

StreamMachine Master

Here's a working configuration file for a master (master.json):

{
  "mode": "master",
  "source_port": 8002,
  "master": {
    "port": 8020,
    "password": "super_secure_password"
  },
  "log": {
    "stdout": true,
    "json": {
      "file": "/var/log/streammachine/streammachine.log",
      "level": "info"
    }
  },
  "streams": {
    "test": {
      "key": "test",
      "root_route": true,
      "format": "mp3",
      "seconds": 3600,
      "metaTitle": "Testing",
      "host": "localhost",
      "source_password": "testing"
    }
  }
}

This will activate the master mode, listen on port 8020 for slaves with a defined password and create a test stream. Feel free to use whatever configuration is best for you.

Now launch manually a StreamMachine master with the above configuration file:

cd /srv/StreamMachine
./streammachine-cmd --config ./config/master.json

If all goes well you can request some information from the API:

curl http://a.b.c.d:8020/api/config

StreamMachine Slave

Note your StreamMachine master IP address, port and password and fill them in the configuration below.

Here's a working slave configuration file:

{
  "mode": "slave",
  "slave": {
    "master": "ws://a.b.c.d:8020?password=super_secure_password"
  },
  "cluster": 1,
  "port": 8017,
  "log": {
    "stdout": true,
    "json": {
      "file": "/var/log/streammachine/streammachine.log",
      "level": "info"
    }
  }
}

This will launch a StreamMaster instance in slave mode, point to its master, listen to port 8017 and log. Feel free to adapt.

Note that the cluster configuration number matches the amount of workers you need, and the number shouldn't exceed the amount of CPU cores available.

Now launch manually a StreamMachine slave with the above configuration file:

cd /srv/StreamMachine
./streammachine-cmd --config ./config/slave.json

You should now be able to listen to a stream at http://a.b.c.d:8017/<stream_name>

Using Redis to store configuration

Instead of relying on JSON configuration files, StreamMachine can store and manage its configuration on Redis. This removes the dependency on JSON files, offers live configuration updating, redundancy, and overall a better experience.

You can use a dedicated host for Redis or not, use Redis replication or anything you might think is relevant for your use case.

TODO: Better hints at how an initial configuration can be made with a Redis backed.

Use Redis backend with StreamMachine

In this case, no stream configuration is explicitly needed to start.

• An example configuration file can be:

{
  "port": 8001,
  "source_port": 8002,
  "log": {
    "stdout": true
  },
  "redis": {
    "server": "redis://a.b.c.d:6379"
  }
}

• Start your StreamMachine instance:

./streammachine-cmd --config /srv/config/standalone-redis.json

It shouldn't find any configuration available on Redis or anywhere.

• Create a new stream named my_new_stream using the API (there might be a better way but that's how I did it)

curl -F 'key=my_new_stream' http://a.b.c.d:8001/api/streams

• You can check there's a initial basic configuration by requesting the API:

curl  http://a.b.c.d:8001/api/streams/my_new_stream/config

• Create a JSON file containing the initial configuration for your stream (ie.: my_new_stream.json):

{
  "key": "my_new_stream",
  "root_route": true,
  "format": "mp3",
  "seconds": 3600,
  "metaTitle": "Testing",
  "host": "localhost",
  "source_password": "testing"
}

• Send the configuration to Redis:

$ curl -H "Content-Type: application/json" -H 'Accept: application/json' -X PUT --data @config/my_new_stream.json http://a.b.c.d:8001/api/streams/my_new_stream/config

Note: you could as well have updated each entry manually, but it's a bit longer.

You should now be able to stream to your master StreamMachine host with the proper credentials and information.

Now, configuration will survive crashes and other daily casualties.