mirror of https://github.com/agessaman/meshcore-bot.git synced 2026-05-11 01:57:03 +00:00

Files

T

agessaman aa2677bc4b Add Unix signal handling for graceful shutdown and config reload

- Introduced a new function to configure Unix signal handlers for SIGTERM, SIGINT, and SIGHUP, allowing for graceful shutdown and in-process configuration reload.
- Updated the main function to utilize the new signal handling setup, improving the bot's responsiveness to system signals.
- Enhanced documentation in the service installation guide to clarify the use of the reload command for configuration changes without restarting the service.

These changes improve the bot's operational flexibility and user experience during configuration updates.

2026-03-29 20:32:54 -07:00

5.7 KiB

Raw Blame History

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.7+ (Python 3.12+ recommended; on 3.11 the meshcore dependency has an f-string bug — the install script patches it automatically)
Root/sudo access
MeshCore-compatible device

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
```

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 in place (no process restart):

sudo systemctl reload meshcore-bot

Use restart when connection/radio settings changed (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)

If the bot fails on import with this error in meshcore/commands/contact.py, you are on Python 3.11 and the meshcore dependency uses an f-string that only works on Python 3.12+.

Options:

Recommended: Use Python 3.12+ (create the venv with python3.12 if available, then re-run ./install-service.sh --upgrade).
Or: Re-run the install script so it can patch the installed package:
sudo ./install-service.sh --upgrade
The script detects Python 3.11 and patches the meshcore file in the venv.
Manual patch: Edit /opt/meshcore-bot/venv/lib/python3.11/site-packages/meshcore/commands/contact.py, find the line containing contact["adv_name"] inside the f-string, and change it to contact['adv_name'] (single quotes around adv_name).

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:

Check the logs: sudo journalctl -u meshcore-bot -f
Verify configuration: sudo nano /opt/meshcore-bot/config.ini
Test manually: sudo -u meshcore python3 /opt/meshcore-bot/meshcore_bot.py

5.7 KiB Raw Blame History