ops-jrz1/docs/dev-admin.md

Dev Account Administration

Guide for managing dev accounts on the maubot development server.

Adding a Dev

1. Get the dev's SSH public key (they run cat ~/.ssh/id_ed25519.pub)

2. SSH to the server and run:

   sudo /path/to/scripts/dev-add.sh <username> '<ssh-public-key>'
   

   Example:

   sudo ./scripts/dev-add.sh alice 'ssh-ed25519 AAAAC3... alice@laptop'
   

3. The script will output onboarding instructions - send these to the dev.

What Gets Created

• Unix user account with SSH access
• ~/plugins/hello_<username>/ - starter maubot plugin
• The plugin includes a working hello/ping bot

Removing a Dev

sudo ./scripts/dev-remove.sh <username>

With archive (saves home directory before deleting):

sudo ./scripts/dev-remove.sh <username> --archive

Archives are saved to /var/backups/devs/.

Maubot Setup (One-Time)

After adding the first dev, set up the shared test environment:

1. Create a Matrix bot user for devs (via Element or API)

2. In maubot admin (http://localhost:29316):

   • Add the bot user as a client
   • Devs will create instances using this client

3. Create #devs-sandbox room:

   • Create the room in Matrix
   • Invite the bot user
   • Give devs the room ID/alias

Monitoring

Check Dev Plugin Status

# See what plugins are loaded
curl -s http://localhost:29316/_matrix/maubot/v1/plugins \
  -H "Authorization: Bearer <token>" | jq

View Dev Directories

ls -la /home/*/plugins/

Check Maubot Logs

journalctl -u maubot -f

Troubleshooting

Dev Can't Connect

1. Verify user exists: id <username>
2. Check SSH key: cat /home/<username>/.ssh/authorized_keys
3. Check SSH logs: journalctl -u sshd | grep <username>

Plugin Won't Load

1. Check file permissions:

   ls -la /home/<username>/plugins/
   

2. Verify .mbp file structure:

   unzip -l /home/<username>/plugins/*/dist/*.mbp
   

Disk Space

Monitor dev disk usage:

du -sh /home/*/