Status: canonical. Updated 2026-09-04. Audience: operators standing up bbsengine6 for the first time.

Goal

Stand up bbsengine6 from a clean checkout in roughly five minutes: install OS and Python deps, build the wheel, bring up the database, run the BBS door, and confirm the public website renders.

1. OS packages (Debian / Ubuntu)

sudo apt-get install \
 postgresql postgresql-contrib libpq-dev \
    python3 python3-venv python3-dev build-essential \
    php8.1 php8.1-cli php8.1-pgsql libapache2-mod-php \
    apache2 libapache2-mod-rewrite

PHP extensions pdo and pgsql are pulled in by php8.1-pgsql. Smarty and HTML_QuickForm2 come from PEAR:

sudo pear install html_quickform2 Smarty Log

2. Python package

Install into Python 3.10 (mediapipe does not support 3.13+):

cd bbsengine6/py/src
python3.10 -m build
python3.10 -m pip install dist/bbsengine6-*.whl --force-reinstall

Editable install for development:

cd bbsengine6/py
python3 -m pip install -e .

3. PHP deps (Composer)

cd bbsengine6
composer install

This pulls erusev/parsedown-extra (declared in composer.json) into vendor/.

4. Bring up the database

python -m bbsengine6.startup is the idempotent bootstrap. It runs the backend.check* routines (role provisioning, schema ownership, schema import), then opens the interactive console menu.

python -m bbsengine6.startup

For a non-interactive bring-up, use the stage_one routine directly (see py/src/bbsengine6/backend/).

The startup wizard expects PostgreSQL to be reachable as the current user (typically via ident or peer auth on the local socket). The dedicated zoid6 role is created by backend.checkzoid6role and the five SECURITY DEFINER helpers are reassigned to it by backend.checkzoid6owner — both idempotent.

5. Run the BBS door

The bed console script is the TUI client:

bed

For browser/CLI clients, run the WebSocket daemon. The router is loaded from zoid6.api.handler.MessageRouter:

bed --router zoid6.api.handler.MessageRouter \
    --config /etc/zoid6/bed.json

bed is the thin shim in py/src/bbsengine6/bed.py; the daemon lifecycle (auth, services, signal handling) lives in the bed package above this repo. The daemon opens a TCP/WS port that the net/transport.py WebSocket clients connect to.

6. Serve the public website

The public website (org + com sites, including the handbook tree under /handbook/<v>/<path>) is served by Apache + mod_php + Smarty. No Python app server is needed: handbook chapters are read from disk at request time by engine/router.php and rendered via the shared \bbsengine6\markdown\parseDocument primitive (matching teos's teospath path). Drop the org vhost config into place and reload:

sudo cp www/org/htaccess-prod /var/www/.../.htaccess   # per your layout
sudo apache2ctl configtest
sudo systemctl reload apache2

Then visit http://localhost/handbook/ for the docs and http://localhost/engine/ for the public site.

7. Verify

Check	Command
Package installed	python -c "import bbsengine6; print(bbsengine6.__file__)"
Database reachable	python -m bbsengine6.startup (re-run is safe)
bed on PATH	which bed
Apache config valid	sudo apache2ctl configtest
Handbook renders	curl -fsSL http://localhost/handbook/ \| head
Composer install clean	composer validate --no-check-publish

Next steps

• Security model — ./SECURITY.md summarises the Phase 0-5 hardening and links to ../ROBUSTNESS_REVIEW.md.
• Router operation — ./ROUTER.md documents the /engine/router.php entry point and its handler chain.
• Build / install notes — the python -m build + pip install --force-reinstall sequence and the Python 3.10 constraint are captured in the CHANGELOG.md build-system entries.