Merge branch 'developer_documentation' into 'dev'
Developer documentation See merge request Shinobi-Systems/Shinobi!9merge-requests/35/head
Moe
commit
6331b8d1e2
|
|
@ -0,0 +1,103 @@
|
||||||
|
Shinobi Developer Guide
|
||||||
|
=======================
|
||||||
|
|
||||||
|
General Devlopment Outline
|
||||||
|
--------------------------
|
||||||
|
Shinobi [currently] runs directly out of the repository rather than from a package you install.
|
||||||
|
A full Shinobi install will try to embed itself into the system, so ideally a machine running
|
||||||
|
Shinobi would only be running Shinobi; but when developing Shinobi that would be fairly
|
||||||
|
inconvenient. This guide is going to outline a development process where Shinobi will be fairly
|
||||||
|
contained, and development won't have any wide reaching effects on the system or generally require
|
||||||
|
any sort of super user access.
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
=============
|
||||||
|
You'll need Node and NPM, and for this guide we recommend you set up a user-local install of
|
||||||
|
[NVM](https://github.com/creationix/nvm) and install the latest LTS release. Keeping the Node
|
||||||
|
installation managed and separate from the system Node/NPM will help keep things clean and
|
||||||
|
contained.
|
||||||
|
|
||||||
|
You'll also need either MariaDB/MySQL or SQLite (version 3) or both. SQLite will be esepcially
|
||||||
|
easy to develop with as clearing the DB is as simple as deleting a file and you can keep the DB
|
||||||
|
instance you're working with by copying it.
|
||||||
|
|
||||||
|
Development
|
||||||
|
===========
|
||||||
|
First off you need to clone the Shinobi repository. Either the regular Shinobi repository or the
|
||||||
|
CE repository should work, but the regular will likely have more updates (but has a different
|
||||||
|
license). If you're specifically concerned about OSS then just clone the CE edition, but if
|
||||||
|
you're more concerned about fixing an issue or adding a feature then go for the regular
|
||||||
|
repository. Be sure to work on a fork of the repository if you intend to submit a patch/merge
|
||||||
|
request.
|
||||||
|
|
||||||
|
Obtaining the repository
|
||||||
|
------------------------
|
||||||
|
To clone Shinobi:
|
||||||
|
```sh
|
||||||
|
git clone https://gitlab.com/Shinobi-Systems/Shinobi.git
|
||||||
|
```
|
||||||
|
|
||||||
|
or to clone Shinobi CE:
|
||||||
|
```sh
|
||||||
|
git clone https://gitlab.com/Shinobi-Systems/ShinobiCE.git
|
||||||
|
```
|
||||||
|
Then cd into either the "Shinobi" or "ShinobiCE" directory.
|
||||||
|
|
||||||
|
Grabbing packages
|
||||||
|
-----------------
|
||||||
|
To install the required Node packages you need to install them with NPM:
|
||||||
|
```sh
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
If the install fails you may need to install additional packages on your system or you may need
|
||||||
|
to change how you installed Node/NPM or change your installation method.
|
||||||
|
|
||||||
|
Setting your cloned repository for quick development
|
||||||
|
----------------------------------------------------
|
||||||
|
First we need a base conf.json to modify. Shinobi doesn't have a conf.json by default as
|
||||||
|
adding it to the repository would end up conflicting or altering the configuration on running
|
||||||
|
instances of Shinobi whenever someone updated.
|
||||||
|
```sh
|
||||||
|
cp conf.sample.json conf.json
|
||||||
|
```
|
||||||
|
Generally for development SQLite is going to be easier with SQLite, as we don't have to maintain
|
||||||
|
a MariaDB/MySQL installation and we may need to reset the database often. To set the DB to SQLite:
|
||||||
|
```sh
|
||||||
|
node tools/modifyConfiguration.js databaseType=sqlite
|
||||||
|
```
|
||||||
|
You can confirm this worked by checking conf.json for the following line
|
||||||
|
\[near the end of the file\]:
|
||||||
|
```json
|
||||||
|
"databaseType": "sqlite"
|
||||||
|
```
|
||||||
|
|
||||||
|
Currently Shinobi doesn't use a model framework or seeding system, so setting up the database
|
||||||
|
basically involves copying the pre-set instance bundled with the repository:
|
||||||
|
```sh
|
||||||
|
cp sql/shinobi.sample.sqlite shinobi.sqlite
|
||||||
|
```
|
||||||
|
|
||||||
|
### Resetting the DB
|
||||||
|
If you need to reset the database, you can now do so by deleting the shiobi.sqlite file and
|
||||||
|
copying the sql/shinobi.sample.sqlite file again. Just be sure to stop any running Shinobi
|
||||||
|
instances before you do so.
|
||||||
|
|
||||||
|
Enabling the Super User Interface
|
||||||
|
---------------------------------
|
||||||
|
In order to access the "Super User Interface", where we'll create our initial users, we need to
|
||||||
|
copy the super.sample.json file to super.json:
|
||||||
|
```sh
|
||||||
|
cp super.sample.json super.json
|
||||||
|
```
|
||||||
|
And that's it! As long as that file exists we can access the Super User Interface. The default
|
||||||
|
login information is user: 'admin@shinobi.video' password: 'admin'. This can of course be changed;
|
||||||
|
but for development we advise leaving it as the default.
|
||||||
|
|
||||||
|
Running Shinobi
|
||||||
|
---------------
|
||||||
|
Shinobi is usually run with the PM2 process manager, but for development we'll run the "camera"
|
||||||
|
and "cron" processes directy. To monitor output, we recommend you use a terminal multiplexer like
|
||||||
|
byobu, tmux, or screen. In one terminal window, run ```node cron.js``` and in another run
|
||||||
|
```node camera.js```. Shinobi should now be running on port 8080 on your local machine (you can
|
||||||
|
change the port in conf.json) and accessable at http://localhost:8080 in your browser. Any source
|
||||||
|
code changes you make will require restarting either the camera or cron process [or both].
|
||||||
Loading…
Reference in New Issue