agessaman
133a3bb595
Two documentation gaps behind open questions. The [External_Data] repeater_prefix_api_url comment claimed that leaving it empty "disables prefix command functionality" (#70). That is not what happens: the prefix command answers from the bot's own database of heard repeaters, and the API only augments it with node counts from a wider dataset. The wrong comment is a plausible reason the question was asked at all. Corrected, and the JSON contract is now documented in the command reference for anyone serving their own endpoint, since map.w0z.is is defunct and has no drop-in replacement. Also documented the pipx path (#222). The installer already grew a virtualenv in July, which covered the PEP 668 half of that report, but the unanswered part was where config.ini, the database and local/ live under a pipx install. They are all resolved relative to the directory containing config.ini, which means a bare `meshcore-bot` picks up whatever is in the current directory — so the guidance is to pass an absolute --config. Both console scripts are already smoke-tested from an installed wheel in CI, so this path is supported rather than incidental.
2.6 KiB
Installation
Choose how to run the bot:
| Method | Best for |
|---|---|
| Docker | Containers, consistent environments, easy updates |
| Service (systemd) | Linux servers, run at boot, no containers |
| Debian package | make deb in the repo — see README |
| pipx | A single-user install with no repo checkout and no venv management |
Requirements
- Python 3.10+
- MeshCore-compatible device (USB, BLE, or TCP)
pipx
pipx installs the meshcore-bot and meshcore-viewer console scripts into their own
isolated environment, which sidesteps PEP 668 (externally-managed-environment) on
Debian 12+, Ubuntu 23.04+, Fedora and Arch without you managing a virtualenv:
pipx install "git+https://github.com/agessaman/meshcore-bot@v1.0.0"
Upgrade to a newer tag with pipx install --force "git+https://github.com/agessaman/meshcore-bot@vX.Y.Z".
Where your data lives
The bot has no fixed data directory. Everything is resolved relative to the directory
containing your config.ini, so that directory is effectively your install:
| What | Default | Resolved against |
|---|---|---|
| Config | config.ini |
your working directory, unless you pass --config |
| Database | meshcore_bot.db ([Bot] db_path) |
the config file's directory |
| Local plugins | local/ ([Bot] local_dir_path) |
the config file's directory |
Because a bare meshcore-bot looks for config.ini in the current directory, running
it from somewhere else silently starts a different, empty install. Pass an absolute
--config so it is unambiguous:
mkdir -p ~/.local/share/meshcore-bot
cd ~/.local/share/meshcore-bot
# put your config.ini here, then:
meshcore-bot --config ~/.local/share/meshcore-bot/config.ini
The database and local/ are then created alongside that config.ini no matter where
you launch from. Absolute paths in db_path or local_dir_path are used as-is.
For a systemd unit, set WorkingDirectory= to that directory and use the absolute
--config in ExecStart=. Note the service installer is a
separate, self-contained path — it builds its own virtualenv under /opt/meshcore-bot
and does not use pipx.
Development setup
See Getting started for a quick development setup (run from the repo with python meshcore_bot.py).
Upgrading
If you are upgrading from an older release, read the Upgrade guide before restarting the bot.