Web UI Installation Failure on Raspberry Pi 2 (Bullseye): Protobuf version conflict and venv bootstrap issues

[GoodSpeed001]

I'm reporting a series of issues encountered while installing the PiSCSI v25.12.01 on a clean v24.04.01 installation, since we dont have a versions of PiSCSI-v25.12.01-armhf-lite.zip, to install. The installation via easyinstall.sh fails due to recent changes in Python package management, missing implicit dependencies, and version mismatches.

Environment:

• Hardware: Raspberry Pi 2 Model B (ARMv7)
• PiSCSI Board: 2.4a
• OS: Raspberry Pi OS Bullseye (Debian 11)
• PISCSI - v25.12.01
• Python version: 3.9.2
• Initial Pip version: 20.x (Updated to 25.3 during troubleshooting)

Identified Issues & Logs:

1. Protobuf Version Mismatch (Critical) The latest protobuf (6.x) is automatically installed, but it is incompatible with the pre-generated _pb2.py files in the project.

• Error Log: TypeError: Descriptors cannot be created directly. If this call came from a _pb2.py file, your generated code is out of date and must be regenerated with protoc >= 3.19.0.
• Solution: Force downgrade to protobuf==3.20.3.

2. Missing Implicit Dependency (six) The python-pam module requires six to function, but it is not explicitly listed in requirements.txt, leading to a crash on startup.

• Error Log: File "/.../site-packages/pam/__internals.py", line 2, in import six ModuleNotFoundError: No module named 'six'
• Solution: Explicitly add six to the requirements.

3. Venv Bootstrap Failure (ensurepip) The standard python3 -m venv venv command failed to bootstrap the environment correctly on this OS/Arch combination.

• Error Log: The virtual environment was not created successfully because ensurepip is not available.
• Solution: Created venv using --without-pip and installed pip manually via curl https://bootstrap.pypa.io/get-pip.py | python3.

4. Pip Indexing Issues Older versions of Pip (standard on Bullseye) failed with IndexError when parsing the current requirements.txt.

• Solution: Upgraded Pip globally to 25.3 before environment setup.

Suggested Fixes for the Repository:

• Hard-pin protobuf==3.20.3 in python/web/requirements.txt.
• Add six and python-pam as explicit dependencies in requirements.txt.
• Update easyinstall.sh to ensure pip, setuptools, and wheel are upgraded inside the venv before installing other requirements.

Steps to Reproduce:

• Clean install using 2024-04-30-PiSCSI-v24.04.01-armhf-lite.zip with BalenaEtcher
• Configure the OLED option
• Before update version 24.04.01 works like a charm
• Attempted to install the new versions using the script

cd ~/piscsi
git pull
git checkout v25.12.01
./easyinstall.sh

• Observed failures during the environment setup and subsequent service crashes.

[rdmark]

thanks for reporting the issue! so the approach in this release version of piscsi and the Web UI is to leverage Debian's own packaged python libraries when possible, rather than fetching from pypi with pip. what you're seeing here is what happens when pip does not get the --system-site-packages parameter and attempts to install those packages anyways. can you please try deleting the python/web/venv dir and try launching the Web UI again?

as a side note, if you look in the Web UI's requirements.txt you'll see that I commented out those libraries that should use system site packages. another workaround is to uncomment those lines so that pip picks up on the version locks.

BTW, the analysis in your report looks like it's generated by AI. I honestly prefer you didn't do that, and just summarized your observations in your own words. the AI is making assumptions without the full context, which makes it harder to read the report.

[GoodSpeed001]

Hi rdmark,

as requested, I have issue theses commands:
pi@piscsi:~ /piscsi/python/web $ ls -l
total 144
-rw-r--r-- 1 pi pi 47 Apr 30 2024 babel.cfg
-rw-r--r-- 1 pi pi 41 Jan 24 13:00 current
-rw-r--r-- 1 pi pi 21163 Apr 30 2024 genisoimage_hfs_resource_fork_map.txt
-rw-r--r-- 1 pi pi 0 Apr 30 2024 init.py
drwxr-xr-x 3 pi pi 4096 Apr 30 2024 mock
-rw-r--r-- 1 pi pi 128 Jan 23 20:26 package.json
-rw-r--r-- 1 pi pi 53733 Jan 23 20:26 package-lock.json
-rw-r--r-- 1 pi pi 145 Apr 30 2024 pyproject.toml
-rw-r--r-- 1 pi pi 4515 Apr 30 2024 README.md
-rw-r--r-- 1 pi pi 515 Jan 23 20:26 requirements-dev.txt
-rw-r--r-- 1 pi pi 434 Jan 23 20:26 requirements.txt
drwxr-xr-x 2 pi pi 4096 Apr 30 2024 service-infra
drwxr-xr-x 7 pi pi 4096 Jan 24 13:21 src
-rwxr-xr-x 1 pi pi 3798 Jan 23 20:26 start.sh
drwxr-xr-x 5 pi pi 4096 Apr 30 2024 tests
-rwxr-xr-x 1 pi pi 591 Jan 23 20:26 translation_update.sh
drwxr-xr-x 5 pi pi 4096 Jan 24 13:26 venv
drwxr-xr-x 5 pi pi 4096 Jan 24 13:50 venv_backup_funcional
pi@piscsi:~ /piscsi/python/web $ sudo systemctl stop piscsi-web.service
pi@piscsi:~ /piscsi/python/web $ rm -rf /piscsi/python/web/venv
pi@piscsi: /piscsi/python/web $ sudo systemctl start piscsi-web.service
pi@piscsi:~ /piscsi/python/web $

Now I'm in a boot loop to load the website, showing the following messagem:

PiSCSI Web Interface is Starting....
This page will automatically refresh.

First boot and upgrades can take a second while resolving dependencies.

If you're seeing this page for over a minute, please check the logs at sudo journalctl -f

On PI when I issue the command sudo journalctl -f get this:
pi@piscsi:~/piscsi/python/web $ sudo journalctl -f
-- Journal begins at Tue 2024-04-30 02:57:54 BST. --
Jan 24 15:23:00 piscsi PISCSIWEB[7714]: ModuleNotFoundError: No module named 'pam'
Jan 24 15:23:00 piscsi systemd[1]: piscsi-web.service: Main process exited, code=exited, status=1/FAILURE
Jan 24 15:23:00 piscsi systemd[1]: piscsi-web.service: Failed with result 'exit-code'.
Jan 24 15:23:00 piscsi systemd[1]: piscsi-web.service: Consumed 17.949s CPU time.
Jan 24 15:23:00 piscsi systemd[1]: piscsi-web.service: Scheduled restart job, restart counter is at 3.
Jan 24 15:23:00 piscsi systemd[1]: Stopped PiSCSI-Web service.
Jan 24 15:23:00 piscsi systemd[1]: piscsi-web.service: Consumed 17.949s CPU time.
Jan 24 15:23:00 piscsi systemd[1]: Started PiSCSI-Web service.
Jan 24 15:23:05 piscsi sudo[7719]: pi : TTY=pts/0 ; PWD=/home/pi/piscsi/python/web ; USER=root ; COMMAND=/usr/bin/journalctl -f
Jan 24 15:23:05 piscsi sudo[7719]: pam_unix(sudo:session): session opened for user root(uid=0) by pi(uid=1000)
Jan 24 15:23:15 piscsi PISCSIWEB[7715]: Warning: Not running from a valid git repository. Will not be able to update the code.
Jan 24 15:23:17 piscsi PISCSIWEB[7722]: compiling catalog src/translations/sv/LC_MESSAGES/messages.po to src/translations/sv/LC_MESSAGES/messages.mo
Jan 24 15:23:17 piscsi PISCSIWEB[7722]: compiling catalog src/translations/es/LC_MESSAGES/messages.po to src/translations/es/LC_MESSAGES/messages.mo
Jan 24 15:23:17 piscsi PISCSIWEB[7722]: compiling catalog src/translations/zh/LC_MESSAGES/messages.po to src/translations/zh/LC_MESSAGES/messages.mo
Jan 24 15:23:17 piscsi PISCSIWEB[7722]: compiling catalog src/translations/de/LC_MESSAGES/messages.po to src/translations/de/LC_MESSAGES/messages.mo
Jan 24 15:23:17 piscsi PISCSIWEB[7722]: compiling catalog src/translations/fr/LC_MESSAGES/messages.po to src/translations/fr/LC_MESSAGES/messages.mo
Jan 24 15:23:18 piscsi PISCSIWEB[7715]: Starting PiSCSI Web UI ...
Jan 24 15:23:18 piscsi PISCSIWEB[7724]: Traceback (most recent call last):
Jan 24 15:23:18 piscsi PISCSIWEB[7724]: File "/home/pi/piscsi/python/web/src/web.py", line 16, in
Jan 24 15:23:18 piscsi PISCSIWEB[7724]: from pam import authenticate
Jan 24 15:23:18 piscsi PISCSIWEB[7724]: ModuleNotFoundError: No module named 'pam'
Jan 24 15:23:18 piscsi systemd[1]: piscsi-web.service: Main process exited, code=exited, status=1/FAILURE
Jan 24 15:23:18 piscsi systemd[1]: piscsi-web.service: Failed with result 'exit-code'.
Jan 24 15:23:18 piscsi systemd[1]: piscsi-web.service: Consumed 18.006s CPU time.
Jan 24 15:23:18 piscsi systemd[1]: piscsi-web.service: Scheduled restart job, restart counter is at 4.
Jan 24 15:23:18 piscsi systemd[1]: Stopped PiSCSI-Web service.
Jan 24 15:23:18 piscsi systemd[1]: piscsi-web.service: Consumed 18.006s CPU time.
Jan 24 15:23:19 piscsi systemd[1]: Started PiSCSI-Web service.

I had a little help from AI, but I'll try not to use it, never the less following it, allowed me to identify this issue and provide a solution, maybe isn't robust but I think it fixes the issue. (no hard feelings).

Regards,

[GoodSpeed001]

Update #2
I have edit the requirements.txt and uncomment the lines referred to protobuf==3.20.3 and six==1.17.0.
And ran again ./easyscript.sh, select option 1 ( Install or update PiSCSI Service + Web Interface ), I'm waiting to finish the instalation/update, to provide more feedback.

Regards,

[rdmark]

alright so your venv is still in a broken state it seems. when troubleshooting an error like this it's better not to use systemctl but run the start script directly.

first off, did you delete the venv dir with sudo, and verified that it was actually fully deleted before you tried again?

then cd to python/web and run:

sudo ./start.sh

this should give us a cleaner look at what goes wrong

[GoodSpeed001]

Hi rdmark,

I understand your point, however, even after deleting the venv directory using this command "rm -rf ~/piscsi/python/web/venv", I check the folder has been removed, then I issue the command "sudo systemctl start piscsi-web.service" and the website didn't start, giving the errors I provide earlier.
So I though to edit the requirements.txt and uncomment the lines referred to protobuf==3.20.3 and six==1.17.0.
And ran again ./easyscript.sh, select option 1 ( Install or update PiSCSI Service + Web Interface ).
I'm still waiting to finish the instalation/update, to provide more feedback.

[rdmark]

well the error above is for the pam library so nothing to do with protobuf and six. please use the start.sh script instead of systemctl because the latter will mask a lot of the actual errors leading up to the fail state

[GoodSpeed001]

after easyscript.sh finished, I tried to access the website, no luck.
then I have issue

pi@piscsi:~ /piscsi/python/web $ sudo ./start.sh
compiling catalog src/translations/sv/LC_MESSAGES/messages.po to src/translations/sv/LC_MESSAGES/messages.mo
compiling catalog src/translations/es/LC_MESSAGES/messages.po to src/translations/es/LC_MESSAGES/messages.mo
compiling catalog src/translations/zh/LC_MESSAGES/messages.po to src/translations/zh/LC_MESSAGES/messages.mo
compiling catalog src/translations/de/LC_MESSAGES/messages.po to src/translations/de/LC_MESSAGES/messages.mo
compiling catalog src/translations/fr/LC_MESSAGES/messages.po to src/translations/fr/LC_MESSAGES/messages.mo
Starting PiSCSI Web UI ...
Traceback (most recent call last):
File "/home/pi/piscsi/python/web/src/web.py", line 16, in
from pam import authenticate
ModuleNotFoundError: No module named 'pam'
pi@piscsi:~/piscsi/python/web $

[GoodSpeed001]

I had to use AI to edit the start.sh script and the piscsi-web.service to ensure compatibility with the Raspberry Pi 2.
The changes fix the ensurepip limitations and ensure that all dependencies, like python-pam, are correctly loaded from the virtual environment by the systemd service during boot.

start.sh

#!/usr/bin/env bash
set -e

cd "$(dirname "$0")"

# Verify system packages
ERROR=0
for cmd in genisoimage python3 unzip unar; do
    if ! command -v $cmd &> /dev/null ; then
        echo "$cmd could not be found."
        ERROR=1
    fi
done
if [ $ERROR = 1 ] ; then exit 1; fi

# Create or repair the venv
if ! test -e venv/bin/activate; then
    echo "Creating/Repairing python venv for RPi2 compatibility..."
    python3 -m venv venv --system-site-packages --without-pip
    curl -sS https://bootstrap.pypa.io/get-pip.py | ./venv/bin/python3
    
    source venv/bin/activate
    pip3 install --upgrade pip setuptools wheel
    pip3 install -r requirements.txt
else
    source venv/bin/activate
fi

# Compile translations
pybabel compile -d src/translations

# (Argument parsing logic remains the same)
while [ "$1" != "" ]; do
    PARAM=$(echo "$1" | awk -F= '{print $1}')
    VALUE=$(echo "$1" | awk -F= '{print $2}')
    case $PARAM in
    -p | --web-port) ARG_PORT="--port $VALUE" ;;
    -d | --dev-mode) ARG_DEV_MODE="--dev-mode" ;;
    # ... other cases ...
    esac
    shift
done

PYTHON_COMMON_PATH=$(dirname $PWD)/common/src
export PYTHONPATH=$PWD/src:${PYTHON_COMMON_PATH}
cd src || exit 1

echo "Starting PiSCSI Web UI ..."
python3 web.py ${ARG_PORT} ${ARG_DEV_MODE}

piscsi-web.service

[Unit]
Description=PiSCSI-Web service
After=network-online.target piscsi.service

[Service]
Type=simple
User=pi
Group=pi
WorkingDirectory=/home/pi/piscsi/python/web
# Direct call to venv python ensures all modules (pam, protobuf) are loaded
ExecStart=/home/pi/piscsi/python/web/venv/bin/python3 /home/pi/piscsi/python/web/src/web.py
Restart=always
Environment=PYTHONPATH=/home/pi/piscsi/python/web/src:/home/pi/piscsi/python/common/src
SyslogIdentifier=PISCSIWEB

[Install]
WantedBy=multi-user.target

Please check if this make sense. I have now the last version of PiSCSI (v25.12.01) working with RPi2

[numkem]

I've ran into this issue myself and the issue isn't related to the Pi hardware itself.

I've tracked it down to if you use raspbian not being up to date as if I installed python3-pam through apt it wouldn't fix anything. Not updating the OS wouldn't update python to 3.11 which breaks some dependancies required in the venv.

Here is what I did:

1. Update OS to Raspbian Bookworm
2. Install python3-pam through APT
3. Delete venv in $PISCSI_HOME/python/web/venv
4. Run easyinstall.sh with option 1 to recompile and reinstall everything
5. Restart all services

I didn't need to change any files shipped with the project through git.

[RetroViator]

I getting the "PiSCSI Web Interface is Starting...." loop and the journalctl is producing the same error as above. Though this time on a Raspberry Pi 4 Model B running Bullseye.

I will try upgrading the OS to Bookworm or even Trixie, but I wanted to share my situation while running Bullseye.

I deleted the ~/piscsi/python/web/venv directory. I then ran the ./start.sh script in the /web folder. When I did (both with sudo and without), I received the following:

Creating python venv for web server
Activating venv
Installing requirements.txt
Looking in indexes: https://pypi.org/simple, https://www.piwheels.org/simple
Requirement already satisfied: wheel in /usr/lib/python3/dist-packages (0.34.2)
Looking in indexes: https://pypi.org/simple, https://www.piwheels.org/simple
Collecting babel==2.17.0
Downloading https://www.piwheels.org/simple/babel/babel-2.17.0-py3-none-any.whl (10.2 MB)
|████████████████████████████████| 10.2 MB 40 kB/s
Requirement already satisfied: bjoern==3.2.2 in /usr/local/lib/python3.9/dist-packages (from -r requirements.txt (line 3)) (3.2.2)
Collecting blinker==1.9.0
Downloading https://www.piwheels.org/simple/blinker/blinker-1.9.0-py3-none-any.whl (8.5 kB)
Collecting certifi==2025.11.12
Downloading https://www.piwheels.org/simple/certifi/certifi-2025.11.12-py3-none-any.whl (159 kB)
|████████████████████████████████| 159 kB 343 kB/s
Collecting charset-normalizer==3.4.4
Downloading charset_normalizer-3.4.4-cp39-cp39-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl (144 kB)
|████████████████████████████████| 144 kB 1.9 MB/s
Collecting click==8.1.8
Downloading https://www.piwheels.org/simple/click/click-8.1.8-py3-none-any.whl (98 kB)
|████████████████████████████████| 98 kB 440 kB/s
Collecting flask==3.1.2
Downloading https://www.piwheels.org/simple/flask/flask-3.1.2-py3-none-any.whl (103 kB)
|████████████████████████████████| 103 kB 12.9 MB/s
Requirement already satisfied: flask-babel==4.0.0 in /usr/local/lib/python3.9/dist-packages (from -r requirements.txt (line 9)) (4.0.0)
Collecting idna==3.11
Downloading https://www.piwheels.org/simple/idna/idna-3.11-py3-none-any.whl (71 kB)
|████████████████████████████████| 71 kB 3.5 MB/s
Collecting importlib-metadata==8.7.1
Downloading https://www.piwheels.org/simple/importlib-metadata/importlib_metadata-8.7.1-py3-none-any.whl (27 kB)
Collecting itsdangerous==2.2.0
Downloading https://www.piwheels.org/simple/itsdangerous/itsdangerous-2.2.0-py3-none-any.whl (16 kB)
Collecting jinja2==3.1.6
Downloading https://www.piwheels.org/simple/jinja2/jinja2-3.1.6-py3-none-any.whl (134 kB)
|████████████████████████████████| 134 kB 955 kB/s
Collecting MarkupSafe==3.0.3
Downloading markupsafe-3.0.3.tar.gz (80 kB)
|████████████████████████████████| 80 kB 275 kB/s
ERROR: Exception:
Traceback (most recent call last):
File "/usr/share/python-wheels/resolvelib-0.5.4-py2.py3-none-any.whl/resolvelib/resolvers.py", line 171, in _merge_into_criterion
crit = self.state.criteria[name]
KeyError: 'markupsafe'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/cli/base_command.py", line 223, in _main
status = self.run(options, args)
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/cli/req_command.py", line 180, in wrapper
return func(self, options, args)
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/commands/install.py", line 346, in run
requirement_set = resolver.resolve(
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/resolution/resolvelib/resolver.py", line 122, in resolve
self._result = resolver.resolve(
File "/usr/share/python-wheels/resolvelib-0.5.4-py2.py3-none-any.whl/resolvelib/resolvers.py", line 453, in resolve
state = resolution.resolve(requirements, max_rounds=max_rounds)
File "/usr/share/python-wheels/resolvelib-0.5.4-py2.py3-none-any.whl/resolvelib/resolvers.py", line 318, in resolve
name, crit = self._merge_into_criterion(r, parent=None)
File "/usr/share/python-wheels/resolvelib-0.5.4-py2.py3-none-any.whl/resolvelib/resolvers.py", line 173, in _merge_into_criterion
crit = Criterion.from_requirement(self._p, requirement, parent)
File "/usr/share/python-wheels/resolvelib-0.5.4-py2.py3-none-any.whl/resolvelib/resolvers.py", line 82, in from_requirement
if not cands:
File "/usr/share/python-wheels/resolvelib-0.5.4-py2.py3-none-any.whl/resolvelib/structs.py", line 124, in bool
return bool(self._sequence)
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/resolution/resolvelib/found_candidates.py", line 99, in bool
return any(self)
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/resolution/resolvelib/factory.py", line 239, in iter_index_candidates
candidate = self._make_candidate_from_link(
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/resolution/resolvelib/factory.py", line 167, in _make_candidate_from_link
self._link_candidate_cache[link] = LinkCandidate(
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 296, in init
super(LinkCandidate, self).init(
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 144, in init
self.dist = self._prepare()
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 222, in _prepare
dist = self._prepare_distribution()
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 307, in _prepare_distribution
return self._factory.preparer.prepare_linked_requirement(
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/operations/prepare.py", line 480, in prepare_linked_requirement
return self._prepare_linked_requirement(req, parallel_builds)
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/operations/prepare.py", line 523, in _prepare_linked_requirement
dist = _get_prepared_distribution(
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/operations/prepare.py", line 88, in _get_prepared_distribution
abstract_dist.prepare_distribution_metadata(finder, build_isolation)
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/distributions/sdist.py", line 34, in prepare_distribution_metadata
self.req.load_pyproject_toml()
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/req/req_install.py", line 512, in load_pyproject_toml
pyproject_toml_data = load_pyproject_toml(
File "/home/pi/piscsi/python/web/venv/lib/python3.9/site-packages/pip/_internal/pyproject.py", line 75, in load_pyproject_toml
pp_toml = toml.load(f)
File "/usr/share/python-wheels/toml-0.10.1-py2.py3-none-any.whl/toml/decoder.py", line 156, in load
return loads(f.read(), _dict, decoder)
File "/usr/share/python-wheels/toml-0.10.1-py2.py3-none-any.whl/toml/decoder.py", line 510, in loads
ret = decoder.load_line(line, currentlevel, multikey,
File "/usr/share/python-wheels/toml-0.10.1-py2.py3-none-any.whl/toml/decoder.py", line 777, in load_line
value, vtype = self.load_value(pair[1], strictly_valid)
File "/usr/share/python-wheels/toml-0.10.1-py2.py3-none-any.whl/toml/decoder.py", line 875, in load_value
return (self.load_array(v), "array")
File "/usr/share/python-wheels/toml-0.10.1-py2.py3-none-any.whl/toml/decoder.py", line 1021, in load_array
nval, ntype = self.load_value(a[i])
File "/usr/share/python-wheels/toml-0.10.1-py2.py3-none-any.whl/toml/decoder.py", line 875, in load_value
return (self.load_array(v), "array")
File "/usr/share/python-wheels/toml-0.10.1-py2.py3-none-any.whl/toml/decoder.py", line 997, in load_array
a[b] = a[b] + ',' + a[b + 1]
IndexError: list index out of range

[RetroViator]

I was able to get it running using Bookworm, but I did have a wrinkle that slowed me down.

I cloned the repo and the easyinstall script, but I had to manually configure the Apache proxy, including the SSL proxy. I'm not sure why it didn't work using the easyinstall script.