The Book Of Instruction

RohanRelay

A single-page chat built on the Firebase Realtime Database.

What this is

Two files do everything: index.html holds the entire application (markup, styles and script), and this page explains it. Messages live in one Firebase Realtime Database, so every person with the room code sees the same conversation in real time, including everything said before they arrived.

Using it

Founding a hall

Open the site, choose Found a hall, and enter your name.
Give the hall a name, and optionally an entry password.
Press Light the beacon. A six-character room code appears in the header. Share that code with the people you want in the room.

Joining a hall

Choose Join a hall, enter your name and the room code.
If the hall is sealed, a password box appears. Enter the password given by the founder.
All previous messages load immediately, oldest at the top, newest at the bottom.

Talking

Type in the box at the bottom and press Send, or press Enter on a desktop or laptop. Use Shift + Enter for a new line. On phones and tablets the Enter key makes a new line, so use the Send button.
Text and emoji only. Pasted images are refused, and links that point at images, gifs or video are stripped out before sending.
The smiley button opens a small emoji tray; your device keyboard's own emoji work too.

Editing and deleting your own messages

Mouse: right-click one of your messages.
Touch: press and hold one of your messages for about half a second.
Choose Edit message or Delete message. Only the sender sees this menu on their own messages.
An edited message keeps a small edited note in its footer. A deleted message is replaced in everyone's view by a line saying that the message was deleted.

The hall name

Any member may click the name at the top of the chat and type a new one. The room code never changes, so existing invitations keep working.

The menu (top right)

Search - opens a filter bar. Type a keyword and only matching messages remain visible, with a count of matches. Close it to see everything again.
Darkmode - switches between the dark hall and the light parchment theme. Your choice is remembered on that device.
Settings - see below.
Leave hall - returns you to the entry gate.

Settings

Entry password (founder only) - set a new password, or save an empty box to remove it and open the hall.
Message retention - never expire, expire after 10 minutes, or expire after 1 day. The setting applies to the whole room; messages past their age are removed from the database by any member who has the hall open.
Clear history (founder only) - remove messages from the last hour, the last day, or all time.
Delete room (founder only) - removes the room and every message in it from the database, and sends everyone back to the gate.

Setting up Firebase

Already configured

This copy of index.html already contains a working firebaseConfig, so steps 1 to 3 below are only needed if you want to point the site at your own Firebase project. Steps 4 and 5, anonymous sign-in and the database rules, must both be done in the Firebase console before any hall can be created or joined.

You need a free Firebase project with a Realtime Database (not Cloud Firestore).

1. Create the project

Go to console.firebase.google.com and click Add project. Analytics is not needed.
In the left sidebar open Build then Realtime Database, and click Create Database.
Pick a location, then choose Start in test mode for now. Replace the rules with the ones below before sharing the link widely.

2. Register a web app and copy the config

Click the gear icon then Project settings.
Under Your apps click the web icon (</>), give it a nickname, and register it. Hosting is not required.
Copy the firebaseConfig object that is shown.

3. Paste the config into index.html

Open index.html, scroll to the script near the bottom, and replace the placeholder block:

var firebaseConfig = {
  apiKey: "AIza...",
  authDomain: "your-project.firebaseapp.com",
  databaseURL: "https://your-project-default-rtdb.firebaseio.com",
  projectId: "your-project",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "000000000000",
  appId: "1:000000000000:web:abcdef"
};

databaseURL is the important one. If the config Firebase gives you does not include it, copy the URL shown at the top of the Realtime Database page. Regional databases look like https://your-project-default-rtdb.europe-west1.firebasedatabase.app.

If you open the site before editing the file, a setup screen appears where you can paste the config for testing. That copy is stored only in your own browser and is not shared with anyone else, so the file itself must be edited for a real deployment.

4. Enable anonymous sign-in

The rules below rely on a verified user id, so the site signs every visitor in anonymously. In the console open Build then Authentication, click Get started, choose Anonymous under Sign-in method, and enable it. Nobody is asked for an email or password; each browser is simply given a uid that the database can trust. If this is switched off, the gate reports that anonymous sign-in is unavailable.

5. Database rules

A database left in locked mode refuses everything, and test mode lets the whole internet do as it pleases. Open Build then Realtime Database then Rules, paste the ruleset below, and press Publish. It requires a signed-in user, lets only the author edit or delete a message, reserves the password and the room itself for the founder, and allows expired messages to be swept up by anyone. The presence branch lets each visitor register only their own name; it is what fills the @ list and rings the enter and leave chimes.

{
  "rules": {
    "rooms": {
      ".read": false,
      ".write": false,
      "$code": {
        ".read": "auth != null",
        ".write": "auth != null && (!data.exists() || (data.child('owner').val() === auth.uid && !newData.exists()))",

        "name":      { ".write": "auth != null", ".validate": "newData.isString() && newData.val().length <= 40" },
        "owner":     { ".validate": "newData.val() === auth.uid" },
        "createdAt": { ".validate": "newData.val() <= now" },
        "retention": { ".write": "auth != null", ".validate": "newData.isNumber()" },
        "hasPass":   { ".write": "auth != null && data.parent().child('owner').val() === auth.uid" },
        "pass":      { ".write": "auth != null && data.parent().child('owner').val() === auth.uid" },

        "messages": {
          "$id": {
            ".write": "auth != null && ( (!data.exists() && newData.child('uid').val() === auth.uid) || data.child('uid').val() === auth.uid || root.child('rooms').child($code).child('owner').val() === auth.uid || (!newData.exists() && root.child('rooms').child($code).child('retention').val() > 0 && data.child('ts').val() < (now - root.child('rooms').child($code).child('retention').val())) )",
            ".validate": "newData.hasChildren(['uid','name','text','ts'])",
            "uid":  { ".validate": "newData.val() === data.parent().child('uid').val() || newData.val() === auth.uid" },
            "text": { ".validate": "newData.isString() && newData.val().length <= 2000" },
            "name": { ".validate": "newData.isString() && newData.val().length <= 24" },
            "ts":   { ".validate": "newData.isNumber()" }
          }
        },

        "presence": {
          "$uid": {
            ".write": "auth != null && $uid === auth.uid",
            "name": { ".validate": "newData.isString() && newData.val().length <= 24" },
            "at":   { ".validate": "newData.val() <= now" }
          }
        }
      }
    }
  }
}

What this buys you: a stranger who copies your config out of the page still cannot read a room without signing in, cannot forge a message under someone else's uid, cannot edit or delete anyone else's words, and cannot take a password off a hall or destroy a hall that is not theirs. What it does not buy you: privacy from anyone who has both the code and an anonymous account, since the join screen compares the password hash in the browser and therefore has to read pass. Treat the room password as a courtesy lock; move the check to a Cloud Function if it must truly be enforced.

6. Authorised domains

Because the site now uses Authentication, add your GitHub Pages domain (yourname.github.io) under Authentication then Settings then Authorised domains. localhost is allowed by default.

Hosting on GitHub Pages

Create a repository and add index.html, instructions.html, manifest.webmanifest, icon.png and README.md at its root.
Open the repository Settings, then Pages.
Under Source choose Deploy from a branch, pick main and the / (root) folder, and save.
After a minute the site is live at https://yourname.github.io/your-repo/. Share that link plus a room code.

The page must be served over https for full functionality; GitHub Pages does that automatically. Opening the file directly from disk works for a quick test but falls back to a weaker password hash.

How the data is stored

rooms/
  MORIA1/
    name:       "The Council of Elrond"
    owner:      "u1a2b3c"        (anonymous auth uid of the founder)
    createdAt:  1725148800000
    retention:  0                (0, 600000 or 86400000 milliseconds)
    hasPass:    true
    pass:       "<sha-256 hash>"
    messages/
      -Nx1abc.../
        uid:     "u1a2b3c"          (anonymous auth uid of the sender)
        name:    "Peregrin Took"
        text:    "Second breakfast?"
        ts:      1725148900000   (server timestamp, used for ordering)
        edited:  false
        deleted: false
        mentions: ["Frodo"]      (present only when someone was called out)
        replyTo:  { name: "Frodo", text: "..." }
    presence/
      u1a2b3c/
        name: "Peregrin Took"    (removed automatically when the tab closes)
        at:   1725148900000

Honest limits

Identity is an anonymous Firebase account tied to the browser. Clearing site data makes you a new person, and you lose founder rights to rooms you created.
The password gates the join screen, not the database. Anyone signed in who knows the code can read that room. Do not send secrets.
Messages are not encrypted; the project owner can read everything in the Firebase console.
Retention pruning happens in the browsers of people who have the room open. If nobody opens the room, expired messages sit in the database until someone does.

Back to the halls