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)
```yaml
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:

```bash
./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
```bash
# 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
```bash
# 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
```bash
# 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`:
   ```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:

```yaml
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