Moin

Coordinator only ​

The smallest server: one short configuration file, no domain name, no certificates, no port forwarding. It suits a machine at home, a spare laptop or a cheap VPS, and a group of friends who just want somewhere to talk.

Install the server first, or use Docker.

How it works ​

On startup the server creates a permanent identity, its server ID, and registers with the public relay and discovery servers Moin uses by default. The app finds the server by that ID wherever the server happens to be, connects straight to it when the network allows, and goes through a relay when it doesn't. That's why nothing needs to be opened on your router.

The server only needs outbound internet access. If outbound UDP is blocked, connections still work through a relay over HTTPS, with more delay.

1. Write the configuration ​

Create moin-server.toml:

toml
name = "Game Night"
rooms = "managed"

[access]
bootstrap_secret = "correct-horse-battery-staple"
  • name is the community's name, as members see it.
  • rooms = "managed" means rooms are created and edited while the server runs, from the app, instead of being listed in this file.
  • bootstrap_secret is a one-time secret that lets you claim the administrator role from the app. Make up something long and random, for example with openssl rand -base64 24. It stops working after its first use.

The server keeps its data in a data directory next to this file. See Configuration for everything else you can set.

2. Start the server ​

sh
moin-server --config moin-server.toml

Leave it running. The first log line, moin server starting, includes the endpoint_id: that's your server ID. You can also print it at any time from a second terminal:

sh
moin-server admin --config moin-server.toml status
text
Coordinator  7f31a7a6e56661e4711f3e0884ad27eed013b0900e787a9f668353ba93da4243
Access       open
Bootstrap    open
Connected    0

The ID stays the same on every restart, as long as the data directory is kept. Bootstrap open means the administrator role is still waiting to be claimed.

3. Claim the community ​

Now take charge of the community from the app:

  1. In Moin, choose Add a connection and paste the server ID.
  2. Once connected, open the community's More actions menu (⋯) in the connections list and choose Claim community.
  3. Enter the bootstrap secret and choose Claim administrator role.

Your device is now the community's administrator, and the bootstrap secret can't be used again. You can delete it from the configuration file.

From here on, everything below is done in the app. The same menu item now reads Community administration. See Members and access for where everything is.

4. Create rooms ​

A new community has no rooms. Open the community's More actions menu and choose Create room. Give it a name and, if you like, a member limit.

Each room's own More actions menu has Edit room and Delete room.

5. Invite people ​

Open the community's More actions menu, choose Share community, and send your friends the community link. On iPhone or Android this opens the share sheet; on desktop, copy the link from the dialog. Opening it adds the server in Moin. Pasting the server ID into Add a connection works too.

While the server is open, anyone who has the ID can join. That's often all a group of friends needs. To decide who gets in, go on to the next step.

6. Decide who gets in ​

Switch the server to protected mode with invitations. Change the [access] section of the configuration to:

toml
[access]
mode = "protected"
invites_enabled = true

Restart the server. Your device stays in: claiming the administrator role made it a member.

Now invite each person from the app: in Share community, choose how long the link lasts and how many people can use it, then Create invite link. Each link is shown once and opens in the phone's share sheet; you can also share or copy it from the dialog before closing. Opening it in Moin lets a device join, and the device is remembered from then on.

Anyone who joined while the server was open needs an invitation to get back in. For a shared password instead of invitations, see Members and access.

Without the app

Every step above also works from the server's command line: roles set to choose the administrator, rooms create, and invites create. See Command line.

Keep it running ​

  • Back up the data directory. It holds the server ID. If it's lost, the server gets a new ID and everyone has to add it again.
  • Run it as a service so it survives reboots. See Running the server.
  • Your machine being asleep or offline takes the community offline. When it comes back, apps reconnect on their own; it doesn't matter whether its IP address changed.

When you want an address people can type, such as chat.example.com, move on to Behind a reverse proxy. Keep the same data directory and members keep their access and roles; they add the server again using the hostname.