MeshCore Bot Service Installation

This guide explains how to install the MeshCore Bot as a systemd service on Linux systems.

Prerequisites

Linux system with systemd
Python 3.10+ (3.11–3.13 supported in CI; Python 3.9 is not supported in v0.9)
Root/sudo access
MeshCore-compatible device

Alternative: Install from a Debian package (make deb in the repo) instead of the install script. See the README for build instructions.

Quick Installation

Clone and navigate to the bot directory:

git clone <repository-url>
cd meshcore-bot

Run the installation script:
```
sudo ./install-service.sh
```
Configure the bot:
```
sudo nano /opt/meshcore-bot/config.ini
```
Start the service:
```
sudo systemctl start meshcore-bot
```
Check status:
```
sudo systemctl status meshcore-bot
```

Upgrading

After git pull in the repository (or copying new files), run:

sudo ./install-service.sh --upgrade

This updates installed files and dependencies, refreshes the systemd unit, and reloads the service without overwriting your existing config.ini. See Upgrade guide for v0.9 migration notes (Python 3.10+, config aliases, database migrations, etc.).

Manual Installation

If you prefer to install manually:

1. Create Service User

sudo useradd --system --no-create-home --shell /bin/false meshcore

2. Create Directories

sudo mkdir -p /opt/meshcore-bot
sudo mkdir -p /var/log/meshcore-bot

3. Copy Bot Files

sudo cp -r . /opt/meshcore-bot/
sudo chown -R meshcore:meshcore /opt/meshcore-bot
sudo chown -R meshcore:meshcore /var/log/meshcore-bot

4. Install Service File

sudo cp meshcore-bot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable meshcore-bot

5. Install Dependencies

sudo pip3 install -r /opt/meshcore-bot/requirements.txt

Service Management

Start/Stop/Restart

sudo systemctl start meshcore-bot
sudo systemctl stop meshcore-bot
sudo systemctl restart meshcore-bot

Check Status

sudo systemctl status meshcore-bot

View Logs

# Real-time logs
sudo journalctl -u meshcore-bot -f

# Recent logs
sudo journalctl -u meshcore-bot -n 100

# Logs since boot
sudo journalctl -u meshcore-bot -b

Enable/Disable Auto-start

sudo systemctl enable meshcore-bot    # Start on boot
sudo systemctl disable meshcore-bot   # Don't start on boot

Configuration

The bot configuration is located at /opt/meshcore-bot/config.ini. Edit it with:

sudo nano /opt/meshcore-bot/config.ini

After changing configuration, you can reload many settings without a full restart:

sudo systemctl reload meshcore-bot

Or use the admin reload API (requires [Admin] enabled = true in config.ini):

./scripts/reload_config.sh /opt/meshcore-bot/config.ini

This is equivalent to the admin DM command reload. It reloads in-process config; it does not reconnect the radio.

Use restart when connection/radio settings change (serial port, BLE target, TCP host/port, timeout):

sudo systemctl restart meshcore-bot

Service Features

Security

Runs as dedicated meshcore user
No shell access for service user
Restricted file system access
Resource limits (512MB RAM, 50% CPU)

Reliability

Automatic restart on failure
Restart delay of 10 seconds
Maximum 3 restart attempts per minute
Logs to systemd journal

Monitoring

Systemd journal integration
Status monitoring via systemctl
Resource usage tracking

Troubleshooting

Service Won't Start

Check service status: sudo systemctl status meshcore-bot
View logs: sudo journalctl -u meshcore-bot -n 50
Check configuration: sudo nano /opt/meshcore-bot/config.ini
Verify dependencies: sudo pip3 list | grep meshcore

SyntaxError: f-string: unmatched '[' (Python 3.11, older meshcore)

If the bot fails on import with this error in meshcore/commands/contact.py, you may be on an older meshcore package. v0.9 requires meshcore >= 2.3.6.

Options: - Re-run ./install-service.sh --upgrade to refresh the venv with current requirements. - Or use Python 3.12+ for the venv: python3.12 -m venv ... then re-run the install script. - On Python 3.11 only, the install script can patch legacy meshcore f-string issues in the venv automatically.

Permission Issues

Check file ownership: ls -la /opt/meshcore-bot/
Fix permissions: sudo chown -R meshcore:meshcore /opt/meshcore-bot

Connection Issues

Verify device connection (serial port, BLE, etc.)
Check device permissions for service user
Review connection settings in config.ini

High Resource Usage

The service has built-in limits: - Memory: 512MB maximum - CPU: 50% maximum - File descriptors: 65536 maximum

Uninstallation

To completely remove the service:

sudo ./uninstall-service.sh

This will: - Stop and disable the service - Remove systemd service file - Remove installation directory - Remove log directory - Remove service user

File Locations

Component	Location
Service file	`/etc/systemd/system/meshcore-bot.service`
Bot files	`/opt/meshcore-bot/`
Configuration	`/opt/meshcore-bot/config.ini`
Logs	`/var/log/meshcore-bot/` (if configured)
System logs	`journalctl -u meshcore-bot`

Advanced Configuration

Custom Installation Directory

Edit the service file to change the installation directory:

sudo nano /etc/systemd/system/meshcore-bot.service

Change the WorkingDirectory and ExecStart paths.

Custom User

To use a different user, edit the service file and update the installation script.

Environment Variables

Add environment variables to the service file:

[Service]
Environment=PYTHONPATH=/opt/meshcore-bot
Environment=DEBUG=true
Environment=CUSTOM_VAR=value

Support

For issues with the service installation: 1. Check the logs: sudo journalctl -u meshcore-bot -f 2. Verify configuration: sudo nano /opt/meshcore-bot/config.ini 3. Test manually: sudo -u meshcore python3 /opt/meshcore-bot/meshcore_bot.py