Fork me on GitHub
Wabbit

Distributed webcam surveillance and image processing platform with snapshot archive, database index and a RESTful API web server

 Click here for a live demo ! 

Use this easy guide to get up and running with your own Wabbit server. For problems during installation consult the FAQ.

1) Download

Clone three repos:

git clone https://github.com/vmlaker/bites
git clone https://github.com/vmlaker/date
git clone https://github.com/vmlaker/wabbit

2) Build

From the top of the source tree run make, install ODB and then run SCons:

cd wabbit
make -j 2
bash src/bash/install-odb.sh -j 2
scons bites=../bites date=../date -j 2

Make builds your Python virtualenv and Node.js environment, and compiles the client-side code. The shell script installs C++ ODB libraries. The SCons build chain compiles the C++ sources.

3) Configure

Customize your installation in file wabbit.conf:

cp wabbit.conf.in wabbit.conf
vi wabbit.conf

Then create the database user and privileges (you will need to know your MySQL root password):

./python src/py/create.py

4) Test

Make sure your installation works by testing the Recorder:

bin/record -v 10
./python src/py/dump.py

Now try running the server in development mode:

./python src/py/serve.py

Go to http://127.0.0.1:8000 to view the front page.

Next, run the server in production mode:

venv/bin/gunicorn src.py.serve:app --workers 4 --threads 4 --bind 127.0.0.1:8000 --access-logfile -

In production mode you won't see any images until you open access to the image archive via your webserver (we'll do that in a sec). But you can still check the API at http://127.0.0.1:8000/info.

5) Deploy

You can easily publish the snapshot archive and run the API server through Apache HTTPD. Start by first creating a link to your pictures archive inside your system www directory (note that here we're using /var/www/html -- your platform may use a different path).

sudo ./python deploy/httpd/link.py /var/www/html

Then dump a snippet for your VirtualHost configuration:

./python deploy/httpd/dump.py /var/www/html

Cut-and-paste the snippet into your Apache conf file. Then restart your HTTPD server:

sudo systemctl restart httpd.service

Your page is visible at http://localhost/wabbit.

If running SELinux, security policies may forbid HTTPD from reading your pictures directory. If that's the case, change your SELinux security context of your pics dir:

sudo chcon -R -t httpd_sys_content_t /path/to/my/pics

If you have Systemd, it's easy to automate the control of your Wabbit server processes. Build, install and start the services with:

./python deploy/systemd/build.py
sudo ./python deploy/systemd/install.py
sudo ./python deploy/systemd/start.py

Appendix A: Apache reverse proxy

If your Wabbit server is on a private network, you can setup your Internet-facing server as a reverse proxy to it.

Let's say you're running Wabbit on an internal server accessible at http://192.168.1.55/wabbit and you'd like it to be shown at location /bunny of your public homepage web server. One way to do this would be to make your public server act as a proxy, by configuring it's VirtualHost with the following directives:

<Location /bunny>
    ProxyPass http://192.168.1.55/wabbit
    ProxyPassReverse http://192.168.1.55/wabbit
    ProxyHTMLURLMap http://192.168.1.55/wabbit
    AddOutputFilterByType SUBSTITUTE text/html
    Substitute "s|wabbit/|bunny/|ni"
</Location>
RewriteRule ^/bunny$ bunny/ [R]

Appendix B: Teardown

To remove Wabbit from your system, first stop and remove the services. For Systemd:

sudo ./python deploy/systemd/stop.py
sudo ./python deploy/systemd/remove.py

Or, for runit:

sudo ./python deploy/runit/stop.py
sudo ./python deploy/runit/remove.py

Then, clear your achive and remove the database:

./python src/py/prune.py -60
./python src/py/drop.py

Q: When I run make, it fails with /bin/sh: virtualenv: command not found. How do I fix this?

A: You're missing virtualenv, a tool for creating Python Virtual Environments. On YUM systems, you can install it with:

sudo yum install python-virtualenv


Q: Why am I getting ImportError: No module named cv2 ?

A: You're missing the OpenCV Python library. On a YUM system, install it with:

sudo yum install opencv-python


Q: My make command fails with make: npm: Command not found, what do I do? Help!!

A: Your system is missing the Node.js package manager. With YUM, you can install it with:

sudo yum install npm


Q: When I run make, I get EnvironmentError: mysql_config not found. What do I do?

A: You're missing mysql_config. On Ubuntu, install the missing package:

sudo apt-get install libmysqlclient-dev

Or, on Fedora:

sudo yum install mariadb-devel


Q: How do I install C++ bindings for MySQL?

A: With Aptitude get the libmysql++-dev package. Or, with YUM get mysql++-devel.


Q: When I run SCons, I get an error like this: configure: error: g++ does not support plugins; reconfigure GCC with --enable-plugin. What does this mean?

A: Your GCC is missing header files for plugin development. On Ubuntu, install the needed package:

sudo apt-get install gcc-4.8-plugin-dev

On Fedora, install it with:

sudo yum install gcc-plugin-devel

Q: When I run SCons, it bails with sh: convert: command not found, what the heck is this?

A: The build requires ImageMagick. On Fedora, you can install it with:

sudo yum install ImageMagick


Q: When I attempt to record snapshots, I get Cannot open device -1 error. Why is this happening?

A: Your webcam is not detected. Check by making sure your system has a webcam:

ls /dev/video*

On some systems (like Fedora) your user needs to belong to video group. You may need to run:

sudo usermod -a -G video username


Q: When I attempt to record snapshots, I get the error Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock'. What gives?

A: Your MySQL server is probably not running, or perhaps not even installed. On Ubuntu, install and start the server with:

sudo apt-get install mysql-server
sudo service mysql start


Q: When I attempt to record snapshots, I get the error Access denied for user 'bugs'@'localhost' (using password: YES). Please help!

A: You most likely forgot to create the database. Try running:

./python src/py/create.py

(See the Configure section of Install Guide for more details.)


Q: When I try to compile client-side pages, I get /usr/bin/env: node: No such file or directory. What gives?

A: You probably installed node from a package manager, and it is misnamed to nodejs instead of node. Fix this by symlinking the executable:

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


Q: My Apache HTTPD has errors like (13)Permission denied: AH00957: HTTP: attempt to connect to 127.0.0.1:8000 (127.0.0.1) failed. How do I fix this?

A: It might be that SELinux is preventing HTTPD from connecting to port 8000. Try changing the setting with:

sudo setsebool httpd_can_network_connect 1

If that works, make the change permanent (to remain across reboots):

sudo setsebool -P httpd_can_network_connect 1


Wabbit is a webcam recorder and archive server. It comes with a web API and a live surveillance page.

The recorder is written in C++. The multi-threaded image processing pipeline uses Intel Threading Building Blocks templates. The pipeline implements snapshot capture, disk writing and database indexing stages. It's designed to be easily extended with additional image processing steps if needed.

Web server and database tools are written in Python. The web API is implemented in the Flask microframework, and allows random access to stored images. A pruner process maintains the image archive to custom maximum length of time.

Wabbit is written by Velimir Mlaker using open source technologies:

© Copyright 2015, Velimir Mlaker.