HomeLab Bot

Matrix bot for homelab management. Built with Rust and the Matrix Rust SDK.

Features

• Forgejo webhook integration: push commits and CI workflow notifications
• Daily commit reminder via scheduler
• /ping - health check
• /commits - manual commit summary

Requirements

• Rust (edition 2024)
• PostgreSQL
• A Matrix account on any homeserver

Setup

Native

1. Clone the repository:

   git clone https://git.geekiot.tech/geekiot/homelab-bot
   cd homelab-bot
   

2. Create a .env file from the example:

   cp example.env .env
   

3. Edit .env with your configuration:

   Variable	Description	Default
   MATRIX_HOMESERVER	Matrix server URL	-
   MATRIX_USER_ID	Full bot MXID	-
   MATRIX_USER_PASSWORD	Bot account password	-
   MATRIX_SESSION_DIR	Directory for session.json	./
   SERVER_PORT	Webhook listen port	3000
   FORGEJO_WEBHOOK_SECRET	HMAC-SHA256 secret for webhooks	-
   FORGEJO_ROOM_ID	Matrix room ID for notifications	-
   DATABASE_URL	PostgreSQL connection string	-
   SCHEDULER_TIME	Daily reminder time (HH:MM)	18:00

4. Create the database table:

   psql -d your_database -f init.sql
   

5. Build and run:

   RUST_LOG=info cargo run
   

   On first run the bot logs in with password and saves the session to session.json. Subsequent runs restore the session automatically.

Docker

1. Create a .env file from the example:

   cp example.env .env
   

2. Edit .env with your configuration.

3. Start the stack:

   docker compose up -d
   

   This starts both PostgreSQL and the bot. The bot connects to postgres hostname internally, so DATABASE_URL should be:

   DATABASE_URL=postgres://homelab:homelab@postgres:5432/homelab
   

   On first run the bot logs in with password and saves the session to the storage volume. Subsequent runs restore the session automatically.

Nix

If you use Nix, a flake is provided:

nix develop
RUST_LOG=info cargo run

Webhook setup

In your Forgejo repository settings, add a webhook:

• Target URL: http://your-bot:3000/webhook/forgejo
• Secret: same as FORGEJO_WEBHOOK_SECRET
• Events: push, workflow run

Commands

Command	Description
/ping	Health check, replies pong
/commits	Show commit summary for today

Logging

RUST_LOG=homelab_bot=info cargo run    # bot messages only
RUST_LOG=info cargo run                # all logs (default)
RUST_LOG=debug cargo run               # verbose logs

Project structure

.
├── Cargo.toml          # Rust dependencies and metadata
├── flake.nix           # Nix flake for development shell
├── example.env         # Environment variable template
├── templates/          # Askama template files
└── src/
    ├── main.rs         # Entry point
    ├── lib.rs          # Core logic, session management
    ├── config.rs       # Configuration
    ├── templates.rs    # Template structs and markdown helper
    ├── bot.rs          # Command dispatch
    ├── commands/       # Bot commands (ping, commits)
    ├── services/       # External integrations (forgejo)
    ├── scheduler/      # Background tasks (daily reminder)
    └── storage/        # Bot data store (PostgreSQL)