Installation Guide

General Notes and Troubleshooting Tips

USB Webcams

This might save someone some trouble…

In some cases unplugging and then reconnecting USB web cameras may renumber the devices. This changes their hardware device name. Since the Portal configuration needs to match the hardware device names, this can occasionally cause problems.

For reliability, it’s recommended to avoid these types of disconnections while using the application. If this scenario does occur, restarting your Raspberry Pi will restore the original device numbering.

Supervisord

pi_portal makes heavy use of supervisord to manage processes.

If you have custom configuration for supervisord you will encounter problems during install and uninstall. Deploying pi_portal as a docker container is strongly recommended in these types of scenarios.

Older Hardware

On older Raspberry Pi hardware you should give the supervisor processes plenty of time to startup. Once they are fully loaded any excessive CPU usage should drop off.

Installation Method 1: Docker Container

This is probably the simplest approach, but requires installing docker. It’s recommended to use a Raspberry PI OS docker host to eliminate possible problems with GPIO or video hardware access inside the container.

Steps:

Create a configuration file based on your PaaS accounts and GPIOs. (Secure this file with appropriate permissions and ownership: you should disable read or write access for other users.)
Identify the GPIO device. On Raspberry PI OS this is /dev/gpiomem.
Identify the video devices of your webcams. Usually this is /dev/video0 or similar.
Find your timezone identifier.

Install the container as a service:

docker run \
  -d \
  --restart unless-stopped \
  --device [your_gpio_device_name] \
  --device [your_webcam_device_name] \
  -e TZ=[your_timezone_identifier] \
  -v ${PWD}/[your_config_file.json]:/config.json \
  ghcr.io/pi-portal/pi-portal:latest

Log into Slack and start interacting with your camera and sensors.

Important Note:

Any user who is a member of the docker group will have full access to the container!
This includes snapshots, videos and credentials you’ve installed.

Other Operating Systems:

You will run into problems if your linux distribution is missing the gpio or video groups:
- The docker image expects the GPIO hardware (usually /dev/gpiomem) to belong to the gpio group.
- The docker image also expects the video hardware (usually /dev/video0) to belong to the video group.
For this reason it’s recommended to run the container on a Raspberry PI OS system. It’s possible to add these groups via udevadm, but keep in mind this will complicate your deployment.

Installation Method 2: Raspberry PI OS

The pi_portal Debian packages are also fairly straightforward to install:

Steps:

Identify your CPU architecture:
```
uname -m
```
Identify the underlying Debian version of your Raspberry PI OS install:
```
cat /etc/os-release
```
Visit the pi_portal latest release page and download the corresponding Debian package.
Assume root privileges:
```
sudo su
```

Install the Debian package:

# as root
apt update
apt install ./pi-portal_x.x.x-[architecture]_[distribution].deb

Create a configuration file based on your PaaS accounts and GPIOs.
Find your timezone identifier. This may already be configured on your system: check the value of the TZ environment variable.

Install your configuration file:

# as root
export TZ=[your_timezone_identifier] # If necessary ...
portal install_config [your_config_file.json]

Test your installation:
```
# as root
portal version
```
Drop root privileges:
```
# as root
exit
```
Log into Slack and start interacting with your camera and sensors.

Installation Method 3: Other Linux Distributions

You’ll need to roll up your sleeves a little bit when installing pi_portal manually, but it’s not that hard…

Steps:

Identify your CPU architecture:
```
uname -m
```
Visit the pi_portal latest release page and download:
- the correct filebeat tarball for your CPU
- the pi_portal python wheel
Assume root privileges:
```
sudo su
```

Install filebeat:

# as root
tar xvzf filebeat-linux-[x-x-x]-[architecture].tar.gz -C /usr/bin

Install the Python build dependencies. (Commands and exact package names vary by distribution.)
- bash
- build-essential
- libffi-dev
- libssl-dev
- python3 (Versions 3.8 through 3.11 are supported.)
- python3-dev (Versions 3.8 through 3.11 are supported.)
- Note: you may also need to install packages such as python3-venv and python3-pip if they aren’t included in your distribution’s core python3 package.
Install the runtime dependencies. (Commands and exact package names vary by distribution.)
It would be prudent to stop any services launched for motion or supervisor at this point.
- The installer will attempt this as well, but your distribution may have an incompatible init system.

Create the pi_portal user:

# as root
useradd pi_portal --no-create-home -s /bin/false -l

Take a minute and determine what the gpio system group is on your system:
- This linux system group is added to /dev/gpiomem or similarly named devices to allow non-root access to GPIO hardware.
- The user pi_portal needs to be a member of this group.
```
# as root
usermod -a -G gpio pi_portal
```
This group may be named differently, or may not exist at all. Creating this group yourself is possible, via udevadm.
Repeat this same process and identify what the video group is on your system:
- This linux system group allows non-root access to video hardware.
- The user pi_portal needs to be a member of this group.
```
# as root
usermod -a -G video pi_portal
```
This group may be named differently, or may not exist at all. Creating this group yourself is possible, via udevadm.
Create a configuration file based on your PaaS accounts and GPIOs.

Install the pi_portal wheel:

# as root
mkdir -p /opt/venvs
python3 -m venv /opt/venvs/pi_portal 
source /opt/venvs/pi_portal/bin/activate
pip install ./pi_portal-x.x.x-py3-none-any.whl
chown -R pi_portal:pi_portal /opt/venvs/pi_portal
chmod -R o=- /opt/venvs/pi_portal

It’s possible to change the location by setting an environment variable.

Find your timezone identifier. This may already be configured on your system: check the value of the TZ environment variable.

While still acting as root, install your configuration file:

# as root
export TZ=[your_timezone_identifier] # If necessary ...
pi_portal install_config [your_config_file.json]

Confirm your installation was successful:
```
# as root
portal version
```
Drop root privileges:
```
# as root
exit
```
You may need to manually start the supervisor service if the installer doesn’t recognize your init system.
Log into Slack and start interacting with your camera and sensors.