10 · The ground: packaging and operation

A baobab lives for centuries if the ground is good. A mucua lives in schools, culture points and houses of prayer, far from the people who write code: installing and updating has to be a single command, and it has to get back up on its own after it falls.

Files to read (bbx-make-deb repository)

1. COMO-USAR.txt — how to build the package.
2. build.sh — copies the backend and the front build into the tree and calls dpkg-deb; --vendor-wheels for installing without internet.
3. debian-tree/DEBIAN/postinst — the whole installation.
4. debian-tree/lib/systemd/system/*.service|*.timer.
5. debian-tree/etc/nginx/sites-available/baobaxia.
6. debian-tree/usr/sbin/baobaxia-enriquecimento — turns on/installs OCR and Whisper.
7. debian-tree/usr/share/doc/baobaxia/README.Debian — the mucua's manual.

What postinst does

flowchart TD
    A[configure] --> B[Node ≥ 18?]
    B --> C[user baobaxia<br/>shell = git-annex-shell]
    C --> D[~/.ssh/authorized_keys ready]
    D --> E[rsync of the code to /opt/baobaxia]
    E --> F[venv + pip<br/>requirements + extras or vendor-wheels]
    F --> G[backend.env with a new BBX_SECRET_KEY<br/>xmpp.env, frontend.env — only if missing]
    G --> G2[radio/TV? → BBX_CANAIS on/manual/off]
    G2 --> H[nginx: baobaxia site<br/>+ RTMP :1935 if the module is there and BBX_CANAIS ≠ off]
    H --> I[avahi: baobaxia.local]
    I --> J["/usr/local/bin/bbx (wrapper --api-url)<br/>baobaxia-healthcheck"]
    J --> K{credenciais.yaml exists?}
    K -- no --> L[bbx criar-galaxia<br/>asks for a UUID to reinstall an existing mucua]
    K -- yes --> M[verificar_legado.py: warns about old data]
    L --> N[enrichment: OCR/Whisper?]
    M --> N
    N --> O[systemd: api, front, timers]
    O --> P[summary in /etc/baobaxia/instalacao.html]

Rules the script follows: it never overwrites backend.env (the secret cannot change once the mucua has data); it creates the galaxy before starting the API (otherwise the API comes up with an empty view); it never hangs waiting for a terminal (questions time out after 30 s and only appear if there is a /dev/tty).

The variables. There are over a hundred, and almost all are fine-tuning. The new backend.env comes grouped by theme (core, public address, sync, SSH/Tor, federation, enrichment, radio/TV) with only the ones a mucua usually touches; section 4 of README.Debian explains those and only lists the fine-tuning ones; the full reference, with defaults, is docs/baobaxia-configuracao.md in the back. Mind the three look-alikes of the public address: BBX_MUCUA_PUBLIC_URI (identity), BBX_ORIGEM_PUBLICA (absolute links — without it the request Host is used) and BBX_AP_BASE_URL (ActivityPub).

Services

The services run with NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp and only write to /var/lib/baobaxia, /var/log/baobaxia and /opt/baobaxia/back.

Building and updating

cd bbx-v3-front && npm ci && npm run build
cd ../bbx-make-deb
./build.sh --back ../bbx-v3-back --front-build ../bbx-v3-front/build --version 3.3.0
sudo apt install ./dist/baobaxia_3.3.0_all.deb

Before updating an old mucua to 3.3:

sudo -u baobaxia /opt/baobaxia/back/venv/bin/python \
    /opt/baobaxia/back/ferramentas/verificar_legado.py

Diagnostics

journalctl -u baobaxia-api -f
systemctl list-timers 'baobaxia-*'
bbx tor-diagnostico
bbx diagnostico-shell
curl -s http://127.0.0.1:8000/api/v3/health

Practice

1. Read the whole postinst and mark each step that only runs on the first install. What happens if the power goes out in the middle of bbx criar-galaxia?
2. Build a .deb and list its contents (dpkg-deb -c). Did .git go along?
3. Install it on a Debian virtual machine without internet using --vendor-wheels.
4. Why does nginx close /api/v3/xmpp/extauth to the outside of the machine?
5. Install answering "no" to radio/TV. What changes in backend.env, in /etc/nginx/modules-enabled/ and in a channel's editor?

To talk about

• Who, in the community, will read instalacao.html? What needs to be written there for that person?