F0RTHSP4CE Telegram Bot

Build

This project uses Nix flakes to manage dependencies, ensuring a reliable and reproducible build environment. To get started:

1. Install Nix or NixOS by following instructions at nixos.org/download.
2. Enable Nix flakes as per the guide on NixOS Wiki.

Alternatively, install Cargo and Rust using the instructions found at Rust's official site.

To build the project:

• For a release build, run nix build. The resulting binary can be found at ./result/bin/f0bot.
• For setting up a development environment with necessary dependencies, run nix develop. Inside this environment, you can compile the project with cargo build.

Running the Bot Locally

Prerequisites

1. Install diesel_cli with SQLite support:

   cargo install diesel_cli --no-default-features --features sqlite

2. Create local directory and configuration:

   mkdir local
   cp config.example.yaml local/config.yaml

3. Set up the database:

   cd local
   diesel migration run --database-url db.sqlite3 --migration-dir ../migrations

Bot Setup

1. Use @BotFather to create a new Telegram bot, create a test chat with topics, and add the bot as an administrator.
2. Edit local/config.yaml and adjust it as needed, particularly the telegram.token.

Running the Bot

To start the bot, run from the local directory:

cd local
cargo run bot ./config.yaml

Alternatively, you can build and run the release version:

cargo build --release
cd local
../target/release/f0bot bot ./config.yaml

Or using the Nix build:

nix build
cd local
../result/bin/f0bot bot ./config.yaml

Bot Commands

Basic Commands

• /help - Display all available commands
• /status - Show bot status
• /version - Show bot version
• /topics - Show topic list (private chat only)
• /count - Count devices online (via Mikrotik)

Resident Commands (*)

These commands are available only to residents:

General

• /residents - List current residents
• /residents_admin_table - Show residents admin table
• /residents_timeline - Show residents timeline

Shopping List

• /needs - Show shopping list
• /need <item> - Add an item to the shopping list

User Control

• /userctl - Control personal configuration
  • --add-mac XX:XX:XX:XX:XX:XX - Add MAC address for presence detection
  • --remove-mac XX:XX:XX:XX:XX:XX - Remove MAC address
  • --help - Show userctl command help
• /add_ssh <public_key> - Add an SSH public key for yourself
• /get_ssh <username> - Get SSH public keys of a user by username

LDAP Integration

• /ldap_register <args> - Register in LDAP system
• /ldap_reset_password - Reset your LDAP password
• /ldap_update <args> - Update LDAP settings

Utilities

• /tldr - Summarize long discussion (TL;DR)
• /racovina - Show racovina camera image (in resident chat)
• /hlam - Show hlam camera image (in resident chat)
• /open - Open the door
• /temp_open - Generate a temporary guest door access link

Admin Commands (**)

These commands are available only to bot technicians/admins:

• /add_resident <username|ID> - Add a user as a resident
• /remove_resident <username|ID> - Remove a user from residents
• /broadcast - Broadcast a message to all residents (use as a reply to the message you want to send)
• /debug_update_dashboard <args> - Debug dashboard update

Notes

• Commands marked with * are available only to residents
• Commands marked with ** are available only to bot technicians/admins
• The bot supports various internal features like MAC address monitoring for presence detection
• For more details on specific commands, use the command with --help flag where available

Development

Linting and Code Quality

This project uses several tools to maintain code quality and consistency. Run the following command to check all linting rules and run tests:

just check

This command performs:

• Nix linting: deadnix and statix for Nix expressions
• Python linting: mypy type checking and ruff linting
• Rust linting: cargo clippy with strict warnings enabled
• Tests: Full Rust test suite

Code Formatting

To format all code in the project:

just fmt

This formats Rust, Nix, Python, YAML, JSON, Markdown, and TypeScript files.

Database Schema

To regenerate the database schema after migrations:

just schema

Development Conventions

This project follows these conventions:

• Code Style and Lints: Refer to the ./Justfile.
• Commit Messages: Conventional Commits.
• Metric Naming: Prometheus metric and label naming guidelines.