Get Started

Download

If you have questions please post on Reddit or Discord. Due to limited resources support time is limited. Ordering a support package will give you priority for support.

Moe Alam
Download

Requirements

  • MySQL Server and Client
  • Node.js 7.2.0 or higher
    • check your version with nodejs -v or node -v
  • FFMPEG 3.2.4 or higher with libvpx and libx264.
  • Linux or MacOS base operating system capable of running the previously mentioned libraries and programs.
    • Virtual Machines use Linux.
    • Currently Windows cannot natively run Shinobi. This is due to the choice of certain exec commands and not the JavaScript itself. You can adapt it for use on Windows but it will take one with a sharp mind and a bold heart.

Installation

The Ninja Way

The easiest way to install, directly on metal, is through NPM. The following operating systems are supported.

  • Ubuntu 16, Ubuntu 17

  • CentOS, Fedora, RHEL

  1. Ubuntu - Download and Install Node.js, NPM.

    sudo apt update
    sudo apt install curl gnupg2 -y
    curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
    sudo apt install nodejs -y
    sudo apt install npm -y
  1. CentOS / RHEL - Download and Install Node.js, NPM.

    sudo yum update
    sudo yum install curl -y
    curl --silent --location https://rpm.nodesource.com/setup_8.x | bash -
    sudo yum install nodejs npm -y
  2. Install Shinobi

    mkdir Shinobi
    cd Shinobi
    sudo npm install shinobi
    mv node_modules/shinobi/* .
    sudo npm start
  3. You will be asked a series of questions throughout the installation. Please note that the Ninja way will install the Pro version. To use this method in commercial locations you will be required to purchase a subscription to Shinobi Pro.

Docker : Kitematic

Docker is not officially supported and is not recommended. The kitematic method is provided for those who wish to quickly test Shinobi. The Docker files included in the master and dev branches are maintained by the community. If you would like support with Docker please find a community member who maintains the Docker files or please refer to Docker's forum.

  1. Download and Install Kitematic

  2. Search for Shinobi on Kitematic and click ... Then select the tag kitematic. Then click Create.

  3. Once completed you should see a window like this.

  4. Click the Settings tab on the right then click Ports just below it.

  5. Click the Web Address with 8083 next to it. You will be presented with a login screen. The default credentials are as follows.

  6. Updating : Restart the shinobi docker instance to update the following files and folders. They will be overwritten.

    • - camera.js
      - cron.js
      - plugins/motion/shinobi-motion.js
      - plugins/opencv/shinobi-opencv.js
      - UPDATE.sh
      - web/
  7. Enjoy!

Ubuntu : The Easier Way

This installer works well with Ubuntu 16 and 17.

  1. Open Terminal.

  2. Install git command line library.

    apt install git -y
  3. Pull the repository.

    git clone https://github.com/ShinobiCCTV/Shinobi.git Shinobi
  4. Open Shinobi directory.

    cd Shinobi
  5. Start the installer

    chmod +x INSTALL/ubuntu.sh && INSTALL/ubuntu.sh
  6. Packages will be installed. MariaDB will ask to create a password on first installation.

  7. Once complete. Open up http://localhost:8080 in your browser.

    • Note : if you are installed on a remote computer open up the IP in your web browser.

  8. Default credentials are as follows if you chose to install default_data.sql.

    Username : [email protected]
    Password : password
  9. To update Shinobi with git and restart :

    cd Shinobi
    git pull
    pm2 restart camera.js
    pm2 restart cron.js

Ubuntu : The Harder Way

This installer works well with Ubuntu 16 and 17.

Dont have FFMPEG installed?

  1. Open Terminal.

  2. Add the ffmpeg 3.x repo if you are not on Ubuntu 17 or above.

    sudo add-apt-repository ppa:jonathonf/ffmpeg-3
  3. Install the libraries.

    sudo apt update && sudo apt install ffmpeg libav-tools x264 x265
  4. Now run ffmpeg once to see that it works.

    ffmpeg
  5. If you choose to build yourself you must enabled the following flags for Shinobi to work correctly.

    --enable-gpl --enable-version3 --enable-static --disable-debug --disable-ffplay --disable-indev=sndio --disable-outdev=sndio --cc=gcc-5 --enable-fontconfig --enable-frei0r --enable-gnutls --enable-gray --enable-libass --enable-libfreetype --enable-libfribidi --enable-libmp3lame --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libopenjpeg --enable-libopus --enable-librtmp --enable-libsoxr --enable-libspeex --enable-libtheora --enable-libvidstab --enable-libvo-amrwbenc --enable-libvorbis --enable-libvpx --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxvid --enable-libzimg

Dont have Node.js installed?

  1. Open Terminal.

  2. Install Node.js and it's package manager
    Note : #apt-get install node installs something else, not Node.js.

    sudo apt update
    sudo apt install curl gnupg2 -y
    curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
    sudo apt install nodejs -y
    sudo apt install npm -y
  3. Create a symlink to use nodejs.
    pm2 needs this. If you don't plan on using pm2, then ignore this step.

    ln -s /usr/bin/nodejs /usr/bin/node

Dont have MySQL / MariaDB installed?

  1. Open Terminal.

  2. Install MariaDB. First installation of the database will prompt you to set a password for root user in the database.

    apt install mariadb-server mariadb-client -y

Application Install

  1. Open Terminal.

  2. Download Shinobi with wget if you don't have git installed. Do this only if you haven't already downloaded the files.

    wget https://github.com/ShinobiCCTV/Shinobi/tarball/master
  3. Untar the downloaded file. The extracted directory is the shinobi directory.

    tar -xzf master
  4. Rename the directory for easier access. The extracted folder name will be different. moeiscool-Shinobi-XXXXXXX is only an example. Find the real folder name by doing `ls`.

    mv moeiscool-Shinobi-XXXXXXX shinobi
  5. Set permissions on the shinobi directory. Where camera.js is located.

    chmod -R 755 shinobi
  6. Open Shinobi directory.

    cd shinobi
  7. Setup SQL. Go to sql and install the SQL files in your database.

    cd sql
  8. Access MariaDB SQL Database from Terminal. The password will have been set during the installation of MySQL.

    mysql -u root -p
  9. OPTIONAL : Create New SQL User with privileges. If you choose to use your own pre-defined credentials skip this step.

    source ./user.sql
    • or create your own

      CREATE USER 'majesticflame'@'127.0.0.1' IDENTIFIED BY '';
      GRANT ALL PRIVILEGES ON * . * TO 'majesticflame'@'127.0.0.1';
      FLUSH PRIVILEGES;
  10. while still in the SQL client. Install the Shinobi database. It will create a database called ccio.

    source ./framework.sql
  11. OPTIONAL : default_data.sql contains a demo user and a demo jpeg input monitor.

    source ./default_data.sql
  12. After importing the data. Exit the sql client.

    exit
  13. Go up one directory to enter the main directory. Where camera.js is located.

    cd ..
  14. Copy conf.sample.json as another file named conf.json.

    cp conf.sample.json conf.json
  15. Edit conf.json to reflect your sql credentials. I don't reccommend using root.

    nano conf.json

Install Libraries

  1. Run npm install while in the main directory. This will install the libraries Shinobi needs. PM2 is needed to use UPDATE.sh and to Daeomonize the process

    npm install&&npm install pm2 -g
  2. Copy super.sample.json as another file named super.json.

    cp super.sample.json super.json

Launch Shinobi

  1. then to start :

    pm2 start camera.js
  2. Run pm2 logs to see the console for any errors.

    • forever is another program to daemonize, but i've had more success with pm2.

  3. To get your IP you can run the following command.

    ifconfig
  4. Open up http://YOUR_IP:8080 in your browser. The Default Login was originally set by adding default_data.sql.

CentOS, Fedora, RHEL : The Easier Way

This installer works well with CentOS 7.

  1. Open Terminal.

  2. Download and Install Node.js, NPM.

    sudo yum update
    sudo yum install curl -y
    curl --silent --location https://rpm.nodesource.com/setup_8.x | bash -
    sudo yum install nodejs npm -y
  3. Install git command line library.

    yum install git -y
  4. Pull the master repository.

    git clone https://github.com/ShinobiCCTV/Shinobi.git Shinobi
  5. Open Shinobi directory.

    cd Shinobi
  6. Start the installer

    chmod +x INSTALL/centos.sh && INSTALL/centos.sh
  7. Packages will be installed. MariaDB will ask to create a password on first installation.

  8. Once complete. Open up http://localhost:8080 in your browser.

    • Note : if you are installed on a remote computer open up the IP in your web browser.

  9. Default credentials are as follows if you chose to install default_data.sql.

    Username : [email protected]
    Password : password
  10. To update Shinobi with git and restart :

    cd Shinobi
    git pull
    pm2 restart camera.js
    pm2 restart cron.js

Windows : The Hard Way

Warning : Shinobi is running on a process manager, PM2, which sometimes opens command windows for other tasks. Choosing not to use PM2 avoids this command window issue, see below on different start methods.

Please create a Ram Disk or use an SD card for your temporary files. To avoid this you can install Ubuntu Desktop instead. Ubuntu comes with a temporary directory for you to use by default so it is not necessary to set one for it.

You will need a few things installed before being able to run Shinobi.

Install Node.js, MariaDB and your favorite SQL client. The links are posted above.

  1. Once all those are installed download and extract Shinobi and place where you want it to run from.

    Example C:/Shinobi
  2. Open HeidiSQL (or your SQL client) and log in to the MariaDB server now running on your system. The credentials are the ones you put in during the installation of MariaDB.

  3. Open the Query tab on HeidiSQL. Then open your Shinobi directory and locate the folder labeled sql. Drag the following files to your query tab and click the Run button to import the database.

    • framework.sql

    • user.sql

    • default_data.sql

  4. Open the ffmpeg zip you downloaded. Find the folder labelled bin. Copy this folder into your Shinobi directory and rename it to ffmpeg.

    Example C:/Shinobi/ffmpeg
  5. Make a copy of conf.sample.json and rename it to conf.json.

    Set your windowsTempDir inside your conf.json. You must do this on Windows or you may end up with very bad performance and possibly shortening the life of your hardware at the same time.

    It is recommended that you use ImDisk or a SD Card as the temporary directory.

    More information about conf.json file can be found here.

    "windowsTempDir":"R:/Temp"
  6. Open Command Prompt. Click the Start Menu on your Windows taskbar and begin typing cmd.exe. Open the Shinobi directory.

    cd C:/Shinobi
  7. Install the Shinobi libraries.

    npm install pm2 -g
    npm install
  8. Run Shinobi one of two ways.

    • With Process Manager (you can close the initial command windows after starting with automatic restart if process crashes)

      pm2 start camera.js
      pm2 start cron.js
    • The regular way (you must keep the command window open after starting shinobi, no other command windows should be visible.)

      1. node camera.js
      2. Open a new Command prompt window and start the cron script.

        node cron.js

MacOS : Native

  1. Open Terminal.

  2. Install the required system packages git nodejs npm mysql via brew. If you don't have brew, download it from here: http://brew.sh/ If you have these already on your system you can skip this step.

    brew install git nodejs npm mysql
    sudo npm cache clean -f
    sudo npm install -g n
    sudo n stable
  3. Install the ffmpeg package via brew.

    brew install ffmpeg --with-chromaprint --with-fdk-aac --with-fontconfig --with-freetype --with-frei0r --with-game-music-emu --with-libass --with-libbluray --with-libbs2b --with-libcaca --with-libebur128 --with-libgsm --with-libmodplug --with-libsoxr --with-libssh --with-libvidstab --with-libvorbis --with-libvpx --with-opencore-amr --with-openh264 --with-openjpeg --with-openssl --with-opus --with-rtmpdump --with-rubberband --with-schroedinger --with-sdl2 --with-snappy --with-speex --with-tesseract --with-theora --with-tools --with-two-lame --with-wavpack --with-webp --with-x265 --with-xz --with-zeromq --with-zimg
  4. Download the repo via GIT

    git clone https://github.com/moeiscool/shinobi Shinobi && cd Shinobi
    
  5. Import the sql/user.sql SQL file, it will create a SQL user called majesticflame

    cat sql/user.sql | mysql -u root -p
    
  6. Import the sql/framework.sql SQL file, it will create a database called ccio

    cat sql/framework.sql | mysql -u root -p
    
  7. Import the sql/default_data.sql SQL file, it will create a default user and camera source

    cat sql/default_data.sql | mysql -u root -p ccio
    
  8. Run npm install from your Shinobi directory to install the required nodejs packages.

    npm install
    npm install pm2 -g
    
  9. Copy conf.sample.json to conf.json in your Shinobi directory and enter your database connection details

    cp conf.sample.json conf.json
    
  10. Run npm start from your Shinobi directory to start the Shinobi App.

    pm2 start camera.js
    pm2 start cron.js
    
  11. Open up http://YOUR_IP:8080 in your browser.

    • Default Login : This was originally set by adding default_data.sql.

Account Management

Set up Superuser Access

Rename super.sample.json to super.json. Run the following command inside the Shinobi directory with terminal. Passwords are saved as MD5 strings. You only need to do this step once.

cp super.sample.json super.json

Login at http://your.shinobi.video/super.

Username : [email protected]
Password : admin

You should now be able to manage accounts

Set up Sub-Accounts

Login at http://your.shinobi.video/admin. With the main account of the group. If a sub account is used to login to this page it will be directed to the regular dashboard.

Clean up

Set up the cron file

  1. Run cron.js to get data about how much space is used and to clear old videos.

    pm2 start cron.js
    

Updating Shinobi

Getting the latest files

There are 4 way to do this.

  • The easiest way to update is to login to the Superuser panel and click Update to Master. Then Wait! Seriously. just wait about 3 minutes at most. When the panel is back on the web, Shinobi is updated. This is not an action to be taken lightly. Please click it only once!

  • The second easiest way to update is to just overwrite the web,languages,defintions folders and camera.js files.

  • The third way is the Github Pull Method This method only works if you used git to download Shinobi.

    cd Shinobi
    git pull
  • This method will is now deprecated and will be removed in future releases. It will be replaced with a new method only usable by the Superuser.

    Update Shinobi with API Easy, does not update plugins at this time

    This overwrites camera.js, web, and UPDATE.sh

    http://xxx.xxx.xxx.xxx/[API KEY]/update/[UPDATE KEY]

Daemonize and Startup

Keep running and on boot

  1. Start camera.js and cron.js then run check to see they are running under PM2.

    pm2 start camera.js
    pm2 start cron.js
    pm2 list
  2. After camera.js and cron.js are started you can run the following to start them on boot.

    pm2 startup
    pm2 save

Configuration

Default Login

After importing default_data.sql the following login credentials become active.

To change these credentials after logged in.

  1. Login
  2. Click user email located at the top right of the dashboard.
  3. Open Settings.
  4. Change details to your liking.

conf.json

conf.json is the file that you create from conf.sample.json during the install process using the following command from inside the Shinobi directory.

cp conf.sample.json conf.json

Anyway! on to what’s really important. What’s in the file itself. This is the contents of conf.sample.json.

{
  "port": 8080,
  "addStorage": [
      {"name":"second","path":"__DIR__/videos2"}
  ],
  "db": {
    "host": "127.0.0.1",
    "user": "majesticflame",
    "password": "",
    "database": "ccio",
    "port":3306
  },
  "mail":{
    "service": "gmail",
    "auth": {
        "user": "[email protected]",
        "pass": "your_password_or_app_specific_password"
        }
  },
  "cron":{
      "key":"change_this_to_something_very_random__just_anything_other_than_this"
  },
  "pluginKeys":{
      "Motion":"change_this_to_something_very_random____make_sure_to_match__/plugins/motion/conf.json"
  }
}

Available Options for conf.json

Options Required Type Description
cpuUsageMarker no string The marker that is used to search for CPU usage in top command. Default is %Cpu. Some systems, like Puppy Linux, require it be set to CPU.
defaultMjpeg no string A path leading to a JPEG file. This default image is needed for when the camera cannot provide frames.
doSnapshot no boolean By default the snapshot in the top left open its own FFMPEG process for a moment to get a single frame, You can avoid this by turning on JPEG API or setting this option to false.
updateKey no string For updating by API.
streamDir no string default is /dev/shm/streams/. Remember to end with /. Leave it undefined or null to use default. Be careful in using HLS as Stream Type. This directory should be set as somewhere in RAM
videosDir no string default is videos/ in the Shinobi directory. Remember to end with /. Leave it undefined or null to use default.
windowsTempDir no string default is C:/Windows/Temp. If your system is not located on the C: drive then you must add this option in your conf.json file.
DropboxAppKey no string Future releases will hide dropbox functions when this key is left null.
port yes int Port that is used for the Shinobi server instance. Default is 8080
utcOffset yes string Timezone that matches your SQL database.
db yes object The login information for the SQL database
db.host yes string The IP address or domain name. Default is 127.0.0.1
db.user yes string The user name. Default is majesticflame.
db.password yes string The password. Default is no password.
db.database yes string The database name. Default is ccio.
db.port yes int The port number for Shinobi. Default is 3306.
cron no object The object that contains some options for cron.js
cron.deleteOld no boolean cron will delete videos older than Max Number of Days per account. Default is true.
cron.deleteNoVideo no boolean cron will delete SQL rows that it thinks have no video files. Default is true.
cron.deleteOverMax no boolean cron will delete files that are over the set maximum storage per account. Default is true.
mail no object If your Email account uses 2-Step Authentication, like Gmail, then you will be require to create an Application Password.
ssl no object If you would to use SSL (Encryption) you can include this object.
ssl.key yes* string Required if SSL object is present. This is a reference to a file that usually ends in .key.
Example : ssl/server.key will direct to a folder named ssl inside your Shinobi directory.
ssl.cert yes* string Required if SSL object is present. This is a reference to a file that usually ends in .crt.
Example : ssl/server.crt will direct to a folder named ssl inside your Shinobi directory.
ssl.passphrase yes* string If your key and certificate use a passphrase you must define it or SSL will not start.
ssl.port no int This is the port SSL will listen on. If option is undefined 443 will be used.
language no string Default is en_CA. You can check the langauges folder inside the Shinobi directory for more options. You can make more by using node tools/translateLanguageFile.js.
addStorage no object View the sample above for how to structure this object.

Troubleshooting

Finding Problems

Warning : Shinobi is not for the faint of heart. Currently it is still in heavy development. While the large objective is to actually care about the software while writing it : this project started in November 2016, it should be expected to have bugs and the need for further refinement. If you are unable to get through the installation process please skip Shinobi and try Blue Iris.

What to do

For all errors please try the following before posting in the Issues or asking on Discord.

  • Read through the Shinobi Wiki
  • Searching the web.
    • Google, Lukol, anything.
  • Make sure you have installed all the Requirements.
  • Review the Installation Process
  • If you are paying for support package ignore the previous requirements and open a ticket or contact a developer directly.

Posting in the Issues

The following are required when posting in the issues.

  • Must be about Shinobi, not Node.js or a library used by Shinobi
  • Include a snippet of any errors you are describing.
    • If logs are not available, providing some screenshots may be helpful.
  • Must be about a bug.
    • Suggestions must be posted on Discord in the #suggestions channel.

The most common issue

  • TypeError: undefined is not a function.
    • Update to Node.js 7.2.0 or higher.

Support Packages


We will answer your questions about how Shinobi works, the different ways you can use it, and it's documentation. We will keep your installation maintained with the latest stable build.

Ordering a support package also supports the developers.