3d33a45cc9
Learner account management: - learner-add.sh: create accounts with SSH, plugin skeleton - learner-remove.sh: remove accounts with optional archive - plugin-skeleton template: starter maubot plugin Testing: - flake.nix: add checks output for pre-deploy validation - smoke-test.sh: post-deploy service verification Documentation: - learner-onboarding.md: VS Code Remote-SSH setup guide - learner-admin.md: account management procedures Skills: - code-review.md: multi-lens code review skill - orch, worklog: symlinks to shared skills
178 lines
4.6 KiB
Markdown
178 lines
4.6 KiB
Markdown
# Maubot Plugin Development - Learner Onboarding
|
|
|
|
This guide walks you through setting up your development environment for building maubot plugins.
|
|
|
|
## Prerequisites
|
|
|
|
1. **VS Code** with the [Remote-SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
|
|
2. **SSH key pair** - if you don't have one:
|
|
```bash
|
|
ssh-keygen -t ed25519 -C "your-email@example.com"
|
|
```
|
|
3. **Your public key** - send this to the admin:
|
|
```bash
|
|
cat ~/.ssh/id_ed25519.pub
|
|
```
|
|
|
|
## Getting Connected
|
|
|
|
Once the admin has set up your account, you'll receive connection details.
|
|
|
|
### 1. Configure SSH
|
|
|
|
Add this to your SSH config file (`~/.ssh/config` on Mac/Linux, `C:\Users\YOU\.ssh\config` on Windows):
|
|
|
|
```
|
|
Host maubot-dev
|
|
HostName <server-ip>
|
|
User <your-username>
|
|
LocalForward 29316 127.0.0.1:29316
|
|
```
|
|
|
|
Replace `<server-ip>` and `<your-username>` with the values provided by your admin.
|
|
|
|
### 2. Connect with VS Code
|
|
|
|
1. Open VS Code
|
|
2. Press `F1` (or `Cmd+Shift+P` / `Ctrl+Shift+P`)
|
|
3. Type "Remote-SSH: Connect to Host"
|
|
4. Select `maubot-dev`
|
|
5. Wait for VS Code to connect
|
|
|
|
### 3. Open Your Plugin Folder
|
|
|
|
Once connected:
|
|
1. Click "Open Folder"
|
|
2. Navigate to `/home/<your-username>/plugins/hello_<your-username>`
|
|
3. Click "OK"
|
|
|
|
You should see your starter plugin files.
|
|
|
|
## Your First Plugin
|
|
|
|
Your starter plugin responds to two commands:
|
|
- `!hello` - Says hello
|
|
- `!ping` - Responds with pong
|
|
|
|
### Build and Deploy
|
|
|
|
1. Open the integrated terminal in VS Code (`Ctrl+`` ` or `View > Terminal`)
|
|
|
|
2. Build your plugin:
|
|
```bash
|
|
make build
|
|
```
|
|
This creates a `.mbp` file in the `dist/` folder.
|
|
|
|
3. Open the maubot admin UI:
|
|
- In your browser, go to: http://localhost:29316
|
|
- Log in (ask admin for credentials)
|
|
|
|
4. Upload your plugin:
|
|
- Go to "Plugins" tab
|
|
- Click "Upload new plugin"
|
|
- Select your `.mbp` file from `dist/`
|
|
|
|
5. Create an instance:
|
|
- Go to "Instances" tab
|
|
- Click "Create instance"
|
|
- Select your plugin and a bot user
|
|
- Add `#learners-sandbox` to allowed rooms
|
|
- Click "Create"
|
|
|
|
6. Test in Matrix:
|
|
- Join the `#learners-sandbox` room
|
|
- Type `!hello` - your bot should respond!
|
|
|
|
## Plugin Development
|
|
|
|
### File Structure
|
|
|
|
```
|
|
hello_yourname/
|
|
├── maubot.yaml # Plugin manifest (name, version, etc.)
|
|
├── hello_yourname/ # Python module
|
|
│ ├── __init__.py # Module init
|
|
│ └── bot.py # Your bot code
|
|
├── Makefile # Build commands
|
|
└── dist/ # Built .mbp files
|
|
```
|
|
|
|
### Adding Commands
|
|
|
|
Edit `hello_yourname/bot.py`:
|
|
|
|
```python
|
|
from maubot import Plugin, MessageEvent
|
|
from maubot.handlers import command
|
|
|
|
class Bot(Plugin):
|
|
@command.new("hello")
|
|
async def hello_command(self, evt: MessageEvent) -> None:
|
|
await evt.reply("Hello!")
|
|
|
|
# Add your new command here:
|
|
@command.new("dice")
|
|
async def dice_command(self, evt: MessageEvent) -> None:
|
|
import random
|
|
result = random.randint(1, 6)
|
|
await evt.reply(f"🎲 You rolled a {result}!")
|
|
```
|
|
|
|
### Development Workflow
|
|
|
|
1. Edit your code in VS Code
|
|
2. Run `make build` in the terminal
|
|
3. In maubot admin, go to your instance and click "Reload"
|
|
4. Test your changes in Matrix
|
|
|
|
### Makefile Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `make build` | Build the .mbp plugin file |
|
|
| `make check` | Check Python syntax |
|
|
| `make clean` | Remove built files |
|
|
|
|
## Troubleshooting
|
|
|
|
### "Connection refused" when opening localhost:29316
|
|
|
|
The SSH tunnel isn't working. Make sure:
|
|
- You're connected via VS Code Remote-SSH
|
|
- Your SSH config has the `LocalForward` line
|
|
- Try disconnecting and reconnecting
|
|
|
|
### Plugin doesn't appear in maubot
|
|
|
|
- Check that `make build` completed without errors
|
|
- Make sure you uploaded the `.mbp` file from the `dist/` folder
|
|
- Check the maubot logs for errors
|
|
|
|
### Bot doesn't respond to commands
|
|
|
|
- Make sure the bot is in the room (check room members)
|
|
- Check that the room is in "allowed_rooms" in instance config
|
|
- Check maubot logs for errors
|
|
- Commands are case-sensitive: `!hello` not `!Hello`
|
|
|
|
### Syntax errors
|
|
|
|
Run `make check` to validate Python syntax before building.
|
|
|
|
### Need to see logs
|
|
|
|
In the maubot admin UI, go to "Logs" to see recent activity and errors.
|
|
|
|
## Resources
|
|
|
|
- [Maubot Documentation](https://docs.mau.fi/maubot/)
|
|
- [Maubot Plugin Examples](https://github.com/maubot)
|
|
- [Matrix Python SDK (mautrix)](https://docs.mau.fi/python/latest/)
|
|
|
|
## Getting Help
|
|
|
|
- Ask in `#learners-sandbox` - other learners and admins can help
|
|
- Check the maubot logs for error messages
|
|
- Review the maubot documentation
|