83 lines
4.8 KiB
Org Mode
83 lines
4.8 KiB
Org Mode
#+TITLE: MusicLink Bot Integration and Matterbridge Matrix Pivot
|
|
#+DATE: 2026-01-20
|
|
#+KEYWORDS: musiclink, matterbridge, matrix, slack-bridge, mautrix-slack, conduwuit, sops-nix
|
|
#+COMMITS: 2
|
|
#+COMPRESSION_STATUS: uncompressed
|
|
|
|
* Session Summary
|
|
** Date: 2026-01-20
|
|
** Focus Area: Integration of MusicLink bot into ops-jrz1 infrastructure
|
|
|
|
* Accomplishments
|
|
- [X] Analyzed and cloned =musiclink= source code from =ops-jrz1= to local dev environment.
|
|
- [X] Integrated =musiclink= as a Nix Flake input in =flake.nix=.
|
|
- [X] Created =modules/musiclink.nix= to manage systemd services for the bot and its Matterbridge adapter.
|
|
- [X] Extended =services.dev-platform= in =modules/dev-services.nix= to include MusicLink configuration.
|
|
- [X] Migrated Slack tokens to =sops-nix= and added new =musiclink-matrix-token=.
|
|
- [X] Provisioned =@musiclink:clarun.xyz= user on the homeserver via Matrix API.
|
|
- [X] Successfully deployed the configuration to =ops-jrz1= VPS.
|
|
- [X] Verified VM integration tests pass with the new module.
|
|
- [X] Granted server admin privileges to =@musiclink:clarun.xyz= to facilitate room management.
|
|
|
|
* Key Decisions
|
|
|
|
** Decision 1: Pivot to Matrix-mediated bridging
|
|
- Context: =musiclink= requires Matterbridge WebSocket API. Matterbridge (stable) lacks Slack Socket Mode support, which our Slack App requires.
|
|
- Options considered:
|
|
1. Patch Matterbridge to support Socket Mode (high effort).
|
|
2. Use Slack Events API (requires public ingress/TLS management).
|
|
3. Route via Matrix using =mautrix-slack= as the gateway (Matrix-native approach).
|
|
- Rationale: Matrix-mediated routing leverages existing infrastructure (=mautrix-slack=) and treats Matrix as the universal communication bus.
|
|
- Impact: =MusicLink= -> =Matterbridge= -> =Matrix= -> =mautrix-slack= -> =Slack=.
|
|
|
|
** Decision 2: Read-only listener for Slack-bridged rooms
|
|
- Context: Safety constraint to prevent the bot from posting test/automated messages back to Slack during initial setup.
|
|
- Rationale: Configured Matterbridge gateway as =[[gateway.in]]= for the Matrix side.
|
|
- Impact: The bot can see and process links from Slack but cannot post back to the channel.
|
|
|
|
** Decision 3: Use local file path for Flake input (Workaround)
|
|
- Context: =nix flake check= failed to authenticate with =git.clarun.xyz= via HTTPS/SSH.
|
|
- Rationale: Cloned the repo locally and used =git+file:///home/dan/proj/musiclink= to unblock development.
|
|
- Impact: Filed beads issue =ops-jrz1-zr0q= to resolve permanent git access.
|
|
|
|
* Problems & Solutions
|
|
| Problem | Solution | Learning |
|
|
|---------+----------+----------|
|
|
| Matterbridge failed with =not_allowed_token_type= on Slack | Pivoted to Matrix bridge; Matterbridge RTM is incompatible with modern Socket Mode apps | Matterbridge Slack support is lagging behind Slack API changes |
|
|
| MusicLink crashed with "malformed ws URL" | Changed protocol from =http://= to =ws://= in bot config | WebSocket clients are strict about the =ws://= scheme |
|
|
| Matterbridge failed Matrix login with =missing field password= | Added =MxID= to config to trigger token-based auth bypass | Matterbridge needs explicit User ID to use an existing access token |
|
|
| =M_FORBIDDEN= when joining portal room | Granted server admin to bot via =conduwuit --execute= command | Admin status alone doesn't bypass invite-only rules for standard =/join= calls |
|
|
|
|
* Technical Details
|
|
|
|
** Code Changes
|
|
- =modules/musiclink.nix=: Defines systemd services with =DynamicUser= and =LoadCredential= for secret safety.
|
|
- =hosts/ops-jrz1.nix=: Enabled MusicLink, disabled Maubot, added sops secrets.
|
|
- =flake.nix=: Wired up the new input and passed it to configurations and tests.
|
|
|
|
** Commands Used
|
|
#+BEGIN_SRC bash
|
|
# Register Matrix user
|
|
curl -s -X POST -H "Content-Type: application/json" \
|
|
-d '{"username":"musiclink", "password":"...", "auth":{"type":"m.login.registration_token", "token":"..."}}'
|
|
http://127.0.0.1:8008/_matrix/client/v3/register
|
|
|
|
# Grant admin status via Conduwuit console
|
|
conduwuit -c continuwuity.toml --execute "admin users make-user-admin @musiclink:clarun.xyz"
|
|
|
|
# Find Room ID from mautrix-slack DB
|
|
sudo -u postgres psql mautrix_slack -c 'SELECT id, mxid, name FROM portal;'
|
|
#+END_SRC
|
|
|
|
* Process and Workflow
|
|
- Used =nix flake check= and VM integration tests to verify module structure before deployment.
|
|
- Incremental deployment via =nixos-rebuild switch= allowed catching configuration mismatches (=http= vs =ws=, =MxID= requirement).
|
|
- Conscious pivot from a blocked path (Matterbridge Slack) to a viable one (Matrix mediation).
|
|
|
|
* Next Steps
|
|
- [ ] User to invite =@musiclink:clarun.xyz= to the =#music= Matrix room.
|
|
- [ ] Verify message flow: Slack -> Matrix -> MusicLink.
|
|
- [ ] Enable outbound posting (=gateway.out=) once processing logic is verified.
|
|
- [ ] Resolve git access issue for the musiclink flake input.
|
|
- [ ] Close beads task =ops-jrz1-k3e0= (AGENTS.md review).
|