Skip to content

Manual raspiCamSrv Installation

Up

The following procedure describes a manual step by step installation.
For automatic installation, see RaspiCamSrv Installation.

If you want to update an existing installation to the latest version, see Update Procedure.

In case of problems during installation and usage, see Troubleshooting

NOTE: For Debian-Trixie, some of the required packages are already preinstalled. To ensure everything is consistently installed in and run from the raspiCamSrv virtual environment, the respective pip install commands, below, have been extended with a --ignore-installed clause and the Flask server is started with python -m flask ...

Step by Step

  1. Connect to the Pi using SSH:
    ssh <user>@<host>
    with and as specified during setup with Imager.
  2. Update the system
    sudo apt update
    sudo apt full-upgrade
  3. If you intend to take videos and have installed a lite version of the OS, you may need to install ffmpeg:
    Check whether ffmpeg is installed with
    which ffmpeg
    If you get an empty response, install with
    sudo apt install ffmpeg
  4. Create a root directory under which you will install programs (e.g. 'prg')
    mkdir prg
    cd prg
  5. Check that git is installed (which is usually the case in current Bullseye, Bookworm or Trixie distributions)
    git --version
    If git is not installed, install it with
    sudo apt install git
  6. Clone the raspi-cam-srv repository:
    git clone --branch main --single-branch --depth 1 https://github.com/signag/raspi-cam-srv
  7. Create a virtual environment ('.venv') on the 'raspi-cam-srv' folder:
    cd raspi-cam-srv
    python -m venv --system-site-packages .venv
    For the reasoning to include system site packages, see the picamera2-manual.pdf, chapter 9.5.
  8. Activate the virtual environment
    cd ~/prg/raspi-cam-srv
    source .venv/bin/activate
    The active virtual environment is indicated by (.venv) preceeding the system prompt.
    (If you need to leave the virtual environment at some time, use deactivate)
  9. Make sure that picamera2 is available on the system:
    python
    >>>import picamera2
    >>>quit()
    If you get a 'ModuleNotFoundError', see the picamera2 Manual, chapter 2.2, how to install picamera2.
    For raspiCamSrv it would be sufficient to install without GUI dependencies:
    For Bullseye and Bookworm:
    sudo apt install -y python3-picamera2 --no-install-recommends
    For Trixie:
    sudo apt install -y python3-libcamera python3-picamera2 --no-install-recommends
  10. Install Flask 3.x with the virtual environment activated (Step 8).
    Raspberry Pi OS distributions come with Flask preinstalled, however we need to run Flask from the virtual environment in order to see other packages which will be located there.
    pip install --ignore-installed "Flask>=3,<4"

    Make sure that Flask is really installed in the virtual environment:
    which flask should output
    /home/<user>/prg/raspi-cam-srv/.venv/bin/flask
  11. Optional installations:
    The following installations are only required if you need to visualize histograms of photos or if you are interested in using Extended Motion Capturing Algorithms or Stereo Vision.
    For use of USB cameras, OpenCV is required.

    All installations must be done with the virtual environment activated (Step 8)

    Install OpenCV:
    sudo apt-get install python3-opencv

    Install numpy:
    For RPI Zero 2, RPI 1 ... 5:
    pip install --ignore-installed numpy
    (There may be errors, which normally can be ignored)
    For RPI Zero W:
    sudo apt-get install -y python3-numpy

    Install matplotlib:
    For RPI Zero 2, RPI 1 ... 5:
    Trixie:pip install --ignore-installed matplotlib
    (There may be errors, which normally can be ignored)
    Bookworm: pip install --ignore-installed "matplotlib<3.8"
    (The version restriction assures compatibility with numpy 1.x which is required for Picamera2)
    For RPI Zero W:
    sudo apt-get install -y python3-matplotlib

    The following installation is required for enabling the raspiCamSrv API
    Install flask-jwt-extended
    pip install --ignore-installed flask-jwt-extended
    (There may be errors, which normally can be ignored)

    The following installation is only required if you are using a Lite variant of the Debian OS:
    For RPI Zero 2, RPI 1 ... 5:
    pip install --ignore-installed psutil
    For RPI Zero W:
    sudo apt-get install -y python3-psutil

    The following installations are only required if you intend to use a Raspberry Pi AI Camera:

    Install the imx500-all package:
    sudo apt install imx500-all

    Install munkres
    pip install --break-system-packages munkres
    (There may be errors, which normally can be ignored)

    If you intend to use the Gunicorn WSGI server instead of the development WSGI server integrated in Flask (Werkzeug), you need to install Gunicorn:
    pip install --break-system-packages gunicorn
    (There may be errors, which normally can be ignored)

  12. Initialize the database for Flask
    (with raspi-cam-srv as active directory and the virual environment activated - see step 8):
    python -m flask --app raspiCamSrv init-db
  13. Check that the Flask default port 5000 is available
    sudo netstat -nlp | grep 5000
    If an entry is shown, find another free port (e.g. 5001)
    and replace port 5000 by your port in all flask commands, below and also in the URL in step 12.
  14. Start the server
    (with raspi-cam-srv as active directory and the virual environment activated - see step 8):
    Either use the Flask built-in development server:
    python -m flask --app raspiCamSrv run --port 5000 --host=0.0.0.0
    or use Gunicorn as productive server:
    gunicorn -b 0.0.0.0:5000 -w 1 -k gthread --threads 6 --timeout 0 --log-level info 'raspiCamSrv:create_app()'
  15. Connect to the server from a browser:
    http://<raspi_host>:5000
    This will open the Login screen.
  16. Before you can login, you first need to register.
    The first user will automatically be SuperUser who can later register other users (User Management)
  17. After successful log-in, the Live screen will be shown, if at least one camera is connected, otherwise the Info screen.
  18. Done!
  19. For usage of raspiCamSrv, please refer to the User Guide

When the Flask server starts up, it will show a warning that this is a development server.
This is, in general, fine for private environments.
How to deploy with an alternative production WSGI server, is described in the Flask documentation

Gunicorn Settings

When using the Gunicorn WSGI server, specific settings must be used with the raspiCamSrv Flask application.

Number of Workers

Command line: -w 1

Only a single worker must be configured.

Each worker will be a separate process. Multiple workers would run multiple raspiCamSrv Flask processes in parallel.
This would cause conflicts when accessing Raspberry Pi resources, such as cameras and GPIO devices.

Port Binding

By default, Gunicorn binds to 127.0.0.1:8080

It is recommended using the same port as the Flask-internal WSGI server (5000).

Command line: -b 0.0.0.0:5000

Worker Type

Gunicorn supports different Worker Types to be used.
From these, only gthread works for raspiCamSrv, because

  • keep-alive connections are supported, which is essential for MJPEG streaming
  • it uses real OS threads which is essential for multi-threading in raspiCamSrv, Picamera2 and OpenCV

Command line: -k gthread

Numer of Threads

With the gthread worker type, it is necessary to specify the number of threads which can be simultaneously active, because each request will be handled by an own worker thread.

Therefore, the number of threads limits the number of simultaneous MJPEG streams.

On the other hand, when a worker is started, the worker process will pre-create the specified number of threads, regardless of how many clients are connected.

Command line: --threads 6

Every MJPEG stream uses one thread, for example:

So, with --threads 4 and 2 clients showing the Web Cam screen, the 4 threads are used up and another client, trying to stream from a video_feed endpoint, would wait.

Timeout

Gunicorn kills and restarts worker threads which are silent for more than the number of seconds specified in the timeout option.

The default is 30 seconds.

For raspiCamSrv, timout should be avoided.

Command line: --timeout 0

Logging

Command line: --log-level info

'info' is the default log level.

Other valid level names are:

  • debug
  • warning
  • error
  • critical

WSGI APP

raspiCamSrv uses a factory pattern to create the Flask application.

Therefore, the raspiCamSrv WSGI app needs to be ecposed to Gunicorn in the form

Command Line: 'raspiCamSrv:create_app()'