homelab/compose/services/matrix/ROOM-MANAGEMENT.md

Matrix Room Management Guide

Understanding Matrix Room Concepts

Auto-Join Rooms

What they are: Rooms that users automatically join when they create an account.

Configured in: homeserver.yaml (lines 118-120)

auto_join_rooms:
  - "#general:fig.systems"
  - "#announcements:fig.systems"
  - "#support:fig.systems"

How it works:

• When a new user registers, they're automatically added to these rooms
• Great for onboarding and ensuring everyone sees important channels
• Users can leave these rooms later if they want

To add more rooms:

1. Create the room first (using the script or manually)
2. Add its alias to the auto_join_rooms list in homeserver.yaml
3. Restart Synapse: docker restart matrix-synapse

---

Room Directory (Public Room List)

What it is: A searchable list of public rooms that users can browse and join.

Where to find it:

• In Element: Click "Explore rooms" or the + button → "Explore public rooms"
• In Admin Panel: Navigate to "Rooms" section to see all rooms and their visibility

How rooms appear in the directory:

1. Room must be created with visibility: public
2. Room must be published to the directory
3. Users can search and join these rooms without an invite

Room Visibility Settings:

• public - Listed in room directory, anyone can find and join
• private - Not listed, users need an invite or direct link

---

Quick Setup: Create Default Rooms

Run this script to create the three default auto-join rooms:

./create-default-rooms.sh admin yourpassword

This will create:

• #general:fig.systems - General discussion
• #announcements:fig.systems - Important updates
• #support:fig.systems - Help and questions

All rooms will be:

• ✅ Public and searchable
• ✅ Listed in room directory
• ✅ Auto-joined by new users
• ✅ Allow anyone to speak (not read-only)

---

Manual Room Management

Via Synapse Admin Panel

Access: https://admin.matrix.fig.systems

Room Management Features:

1. View All Rooms

   • Navigate to "Rooms" in the sidebar
   • See room ID, name, members, aliases
   • View room details and settings

2. Room Directory Settings

   • Click on a room
   • Find "Publish to directory" toggle
   • Enable/disable public listing

3. Room Moderation

   • View and remove members
   • Delete rooms
   • View room state events
   • See room statistics

4. Room Aliases

   • View all aliases pointing to a room
   • Add new aliases
   • Remove old aliases

---

Via Element Web Client

Access: https://chat.fig.systems

Create a Room:

1. Click the + button or "Create room"
2. Set room name and topic
3. Choose "Public room" for directory listing
4. Set room address (alias) - e.g., general
5. Enable "List this room in the room directory"

Publish Existing Room to Directory:

1. Open the room
2. Click room name → Settings
3. Go to "Security & Privacy"
4. Under "Room visibility" select "Public"
5. Go to "General"
6. Enable "Publish this room to the public room directory"

Set Room as Auto-Join:

1. Note the room alias (e.g., #gaming:fig.systems)
2. Edit homeserver.yaml and add to auto_join_rooms
3. Restart Synapse

---

Room Types and Use Cases

1. General/Community Rooms

# Open to all, listed in directory, auto-join
Preset: public_chat
Visibility: public
History: shared (new joiners can see history)

Best for: General chat, announcements, community discussions

2. Private Team Rooms

# Invite-only, not in directory
Preset: private_chat
Visibility: private
History: shared or invited (configurable)

Best for: Team channels, private projects, sensitive discussions

3. Read-Only Announcement Rooms

# Public, but only admins/mods can post
Preset: public_chat
Visibility: public
Power levels: events_default: 50, users_default: 0

Best for: Official announcements, server updates, rules

---

Room Alias vs Room ID

Room ID: !abc123def456:fig.systems

• Permanent, immutable identifier
• Looks cryptic, not user-friendly
• Required for API calls

Room Alias: #general:fig.systems

• Human-readable name
• Can be changed or removed
• Points to a Room ID
• Used in auto_join_rooms config

Multiple aliases: A room can have multiple aliases:

• #general:fig.systems
• #lobby:fig.systems
• #welcome:fig.systems

All point to the same room!

---

Advanced: Space Management

Spaces are special rooms that group other rooms together (like Discord servers).

Create a Space:

1. In Element: Click + → "Create new space"
2. Add rooms to the space
3. Set space visibility (public/private)
4. Users can join the space to see all its rooms

Use cases:

• Group rooms by topic (Gaming Space, Work Space)
• Create sub-communities within your server
• Organize rooms hierarchically

---

Common Tasks

Add a new auto-join room

1. Create the room (use script or manually)
2. Edit homeserver.yaml:

   auto_join_rooms:
     - "#general:fig.systems"
     - "#announcements:fig.systems"
     - "#support:fig.systems"
     - "#your-new-room:fig.systems"  # Add this
   

3. docker restart matrix-synapse

Remove a room from auto-join

1. Edit homeserver.yaml and remove the line
2. docker restart matrix-synapse
3. Note: Existing users won't be removed from the room

Make a room public/private

Via Element:

1. Room Settings → Security & Privacy
2. Change "Who can access this room"
3. Toggle directory listing

Via Admin Panel:

1. Find room in Rooms list
2. Edit visibility settings

Delete a room

Via Admin Panel:

1. Go to Rooms
2. Find the room
3. Click "Delete room"
4. Confirm deletion
5. Options: Purge messages, block room

Note: Deletion is permanent and affects all users!

---

Troubleshooting

Users not auto-joining rooms

Check:

1. Room aliases are correct in homeserver.yaml
2. Rooms actually exist
3. Synapse was restarted after config change
4. Check Synapse logs: docker logs matrix-synapse | grep auto_join

Room not appearing in directory

Check:

1. Room visibility is set to "public"
2. "Publish to directory" is enabled
3. Server allows public room listings
4. Try searching by exact alias

Can't create room with alias

Possible causes:

• Alias already taken
• Invalid characters (use lowercase, numbers, hyphens)
• Missing permissions

---

Best Practices

✅ Do:

• Use clear, descriptive room names
• Set appropriate topics for all rooms
• Make announcements room read-only for most users
• Use Spaces to organize many rooms
• Regularly review and clean up unused rooms

❌ Don't:

• Auto-join users to too many rooms (overwhelming)
• Make all rooms public if you want privacy
• Forget to set room topics (helps users understand purpose)
• Create duplicate rooms with similar purposes

---

Room Configuration Reference

Power Levels Explained

Power levels control what users can do in a room:

power_level_content_override:
  events_default: 0      # Power needed to send messages (0 = anyone)
  invite: 0              # Power needed to invite users
  state_default: 50      # Power needed to change room settings
  users_default: 0       # Default power for new users
  redact: 50            # Power needed to delete messages
  kick: 50              # Power needed to kick users
  ban: 50               # Power needed to ban users

Common setups:

Open discussion room: events_default: 0 (anyone can talk) Read-only room: events_default: 50, users_default: 0 (only mods+ can post) Moderated room: events_default: 0, but specific users have elevated power

History Visibility

• world_readable - Anyone can read, even without joining
• shared - Visible to all room members (past and present)
• invited - Visible only from when user was invited
• joined - Visible only from when user joined

---

Summary

Auto-Join Rooms: homeserver.yaml:118-120 - Users join automatically on signup Room Directory: Public searchable list - users browse and join Admin Panel: Manage all rooms, visibility, members Element Client: Create/configure rooms with UI

Your setup:

• ✅ Auto-join configured for 3 default rooms
• ✅ Script ready to create them: ./create-default-rooms.sh
• ✅ All new users will join #general, #announcements, #support
• ✅ Rooms will be public and in directory