This is a quick start guide for developing on Shinobi CCTV software. In this article we'll talk about the kind of software and hardware you will need to get going. We'll briefly go over the main directory file structure of Shinobi. And discuss enhancing Shinobi to fit your visual and functional needs.

We'll go over the following :

  • Tools and Preparation
  • Repository File Structure
  • RESTful API
  • Custom Auto Load Modules
  • Detector Plugins
  • White-Labelling

Tools

Code Editor A program to edit the source files. Atom, Brackets
SSH Client (SSH Terminal) A program to connect to your Shinobi server running a recommended version of Linux. Some operating systems like macOS or Linux come with Terminal. Windows users can download Putty. Putty, Terminal, PowerShell
SFTP Client A program to connect to your Shinobi server over the SSH protocol to conduct file transfers similar to FTP protocol. FileZilla
Test Server A server running a recommended version of Linux. This is where your SSH and SFTP Clients will connect to. This is where Shinobi will run. You can get an old laptop, mini pc, or SCB for low footprint testing. Lenovo M92p, Jetson Nano
Description Examples

Preparing Tools

Begin by installing the necessary programs to your workstation. The Code Editor, SSH Client, and SFTP Client. I personally go with Atom, Putty, and FileZilla because my workstation is a windows machine.

Now that you have those, prepare your Test Server by installing an Operating System. We recommend Alma Linux 9.2 for a CPU only experience or Ubuntu 20.04 for servers with NVIDIA GPUs capable of doing Object Detection.

Now that you have an Operating System installed attempt connect over SSH to run the Shinobi Ninja Installer.

Alma Linux installations can select the Rocky 9 installer if Alma Linux is not listed. For Ubuntu you may need to specifically say Yes to installing OpenSSH during the Operating System installation. This will allow SSH connectivity. Learn about using Putty for SSH on Windows at ssh.com.

Essentially get your OS installed and get the IP of the machine, put the IP into Putty and attempt connection. Provide the username and password set during OS installation then run the Ninja Installer.

Once you're all setup, you're ready to dive into the files.

Repository File Structure

Filename Description
Docker Docker configuration files.
INSTALL Installation scripts for Shinobi and other libraries like NVIDIA Drivers.
definitions Dashboard Page Frameworks and other designations.
languages Language files for internationalization
libs Server side core files. The libraries that make Shinobi what it is.
plugins The folder where your detector plugins are downloaded to.
sql Database framework files. These are installed by some installers in the INSTALL folder.
test Scripts that test certain features Shinobi is using. These are not unit tests. These are development files that were used as basis before a feature was added.
tools Support scripts that help you manage your Shinobi installation.
web Web server files. Containing all frontend files, except the Dashboard Page Framework. JS, CSS, and HTML files.
.gitignore List of files that are ignored when committed changes to Shinobi.
.gitlab-ci.yml Auto build controller for Gitlab Registry Docker images.
Dockerfile Dockerfile for creating Docker image
Dockerfile.arm32v7 Dockerfile for ARM32v7 architecture
Dockerfile.nodb Dockerfile for no database configuration
Dockerfile.nvidia Dockerfile for NVIDIA GPU support
LICENSE.md License information
README.md Readme file with project information. See the main website, shop, and documentation for more details.
UPDATE-v2-to-v3.sh Script for updating from Dashboard version 2 to version 3. Don't run this unless you are on the old dashboard and upgrading.
UPDATE.sh General update script. This will use git to update the source. Be careful that this will undo any changes to files not ignored by git.
camera.js The main file of Shinobi. This becomes the primary daemon that makes the application "Shinobi". In other words, a process named "camera.js" under the PM2 list is Shinobi.
conf.sample.json Sample configuration file. This file is copied to conf.json when you run one of the provided installers. You can update the credentials from the Superuser panel or Terminal (SSH).
super.sample.json Superuser default credentials sample file. This file is copied to super.json when you run of the provided installers. You can update the credentials from the Superuser panel or Terminal (SSH).

Default Username : [email protected]
Default Password : admin
package.json NPM package file. List of npm packages Shinobi uses. Some libraries are optionally used.
package-lock.json NPM package lock file. This makes sure the libraries are staying at a specific version number.

RESTful API

Everything the Shinobi dashboard does is through the API. You can make your own Shinobi client with all the same features and more... or less. However you prefer. Learn about using the Shinobi API here.

APIhttps://docs.shinobi.video/api

Custom Auto Load Modules

customAutoLoad Modules are scripts you can use to modify Shinobi's internal operation without modifying the source files themselves. Run custom scripts in Shinobi. Here is an in-depth explanation.

In short, there is a folder found at libs/customAutoLoad. This is where you will put your custom js file or folder that will run automatically on Shinobi start. The aspects you can change are simply written below.

  • EJS Template Replacement, Frontend Render Templates. Learn more here.
  • Loading custom front end JS and CSS. As easy as placing them in a folder within your module's directory. See below for more information.
  • Making changes to the conf.json without editing the file. See below for an example.
  • Running custom functions on internal actions like on Monitor Start or System Ready. You can see all handlers available here. See the samples to learn more about using them.
  • Replacing entire functions to do a custom action instead. This is only possible with some functions, specifically all starting with the s. prefix.

For custom front end JS and CSS you can place them in these folders. Depending on their prefix they will be loaded in the Superuser panel or the Dashboard. Prefix super. for Superuser panel and dash. for Dashboard. More on this in White-Labelling.

  • JS : SHINOBI_FOLDER/libs/customAutoLoad/YOURMODULE/web/libs/js/dash.customTab.js
  • CSS : SHINOBI_FOLDER/libs/customAutoLoad/YOURMODULE/web/libs/css/dash.customTab.css

For loading custom EJS blocks you can place them in this folder. More on this in White-Labelling.

  • EJS : SHINOBI_FOLDER/libs/customAutoLoad/YOURMODULE/web/pages/blocks/customTab.ejs

You can modify the loaded configuration by setting parameters in your custom module's initiator file.

module.exports = function(s,config,lang,app,io){
    config.myNewParamter = true;
}

Detector Plugins

Shinobi comes with a few different plugins bundled together, like TensorFlow, DeepStack, and Yolo. However you can easily make your own by following this guide. This assumes you already have a working detector in either Node.js or Python.

Download plugins by logging into your Superuser panel or following the README provided with the plugin.

White-Labelling

This is only allowed under certain license purchases and/or agreements. We may make exceptions depending on your use case.

Now that you've made it to this part of the article you should know about Custom Auto Load Modules. This is the method we will use to guide you in making a module that will convert your stock Shinobi to a custom version of Shinobi.

We've gone ahead and created a sample module.

If loaded as-is into your Shinobi customAutoLoad folder it will :

  • Modify some text and links appearing on the login screen.
  • Modify the main page title "Shinobi" to "Shinobi Customized"
  • Setting which tabs will be loaded.
  • Adding a Custom Tab with dummy fields including specified js and css files.
  • Create a new account in your Superuser panel on start. Search for "config.staticUsers" in the index.js of the module.

You will notice there are a lot of things commented out or left as default values. Some of those are as follows :

  • Modifying the Icon of the web dashboard.
  • Displaying the landing page selector.
  • Changing the login screen background and css associated to the element.
  • Dark or Light base setting.
  • Changing Monitor Options dropdown class
  • Making Monitor Settings sections hidden by default.
  • Removing ShinobiHub tab.
  • Removing theme selection in Account Settings.

You'll notice a lot of this is modifying the s.definitions parameters, the framework for this can be seen in definitions/base.js.