ShinySDR Manual: Installation

1. Install major dependencies

The following software is required to run ShinySDR. All of it will typically be available in your choice of package manager.

The following software is optional; if it is installed, ShinySDR will automatically enable the relevant features.

2. Download ShinySDR

Obtain a copy of the source tree for ShinySDR. The usual command for this is

git clone https://github.com/kpreid/shinysdr/

which will create a directory named shinysdr.

There is some additional third-party code (mostly JavaScript libraries) which is required and must be downloaded using the provided fetch-js-deps.sh script (or if you prefer, just follow the steps in that script rather than running it).

cd shinysdr
./fetch-js-deps.sh

(Rerunning fetch-js-deps.sh may also be necessary after updating ShinySDR.)

[TODO: Integrate fetch-js-deps or equivalent effects into setup.py.]

3. Decide which way you want to install ShinySDR

There are two different ways you can go about installing and running ShinySDR, and now you need to know which ones you are planning to use.

You can do both of these, if you like; the only hazard is being confused about which version you are running.

4a. setup.py-style installation

If you intend to run ShinySDR directly from the source tree only, skip this step.

ShinySDR provides a setup.py script in the usual fashion for Python packages.

# system-wide installation
python setup.py build
sudo python setup.py install
# current user only
python setup.py install --user
For more installation options see python setup.py install --help and general documentation about how to install Python libraries.

[TODO: change this to talk about pip, maybe after eliminating fetch-js-deps.]

4b. Preparation to run from source tree

If you do not intend to run ShinySDR directly from the source tree, skip this step. Otherwise, install the following Python libraries:

You may wish to create a script to make it easy to start ShinySDR using this directory; for example, I have one like so:
#!/bin/sh
export PYTHONPATH="/wherever/you/put/shinysdr/"
exec python -m shinysdr.main "$@"

5. Configure the server

The server needs a configuration directory where the configuration and state of the server is stored. To create one, run

shinysdr --create config-dir-name
where config-dir-name is the pathname for where you would like the configuration directory created (it can be anywhere). You can then edit config-dir-name/config.py to tell ShinySDR about your hardware, what port(s) you would like it to listen on, and so on; see the page Configuration for details. (The default configuration assumes you have one RF hardware device of a type supported by gr-osmosdr.)

6. Start the server

Run

shinysdr config-dir-name

where config-dir-name is the same as in the previous step. The server will show the URL to visit, or you can use the --go option which will attempt to open it in your default browser.

Note: ShinySDR does not need to run as root. Please don't. (If you get a permission error trying to access USB devices on Linux then you need to install the rtl-sdr udev rules or unplug-replug the device if that's already been done.)

Note: Installing ShinySDR does not do anything to start the server at system boot or restart it if crashed. You will have to provide that on your own if you wish.

See the page Operation for what to do now that you have the server running.