Self-hosting
Accounts and sign-in
Invite people, manage passwords and roles, let people sign in with AT Protocol, choose who may join, and pick the node's host identity.
People sign in to a node in one of two ways:
- Handle and password. An admin invites them, and the node gives them a
did:keyidentity whose key it keeps. - AT Protocol account (a Bluesky account, or any other PDS). They bring their own
did:plc, and the node keeps no key for it.
Either way, a person on the node is a member or an admin. Being a member or admin of the node gives no access to anyone’s repositories: that comes from owning a repo, belonging to an organization, or being added as a collaborator. See Organizations and access.
| Member | Admin | |
|---|---|---|
| Create repos and organizations, add runners for themselves | yes | yes |
| Invite people, change roles, issue reset links | yes | |
| Decide who may join through AT Protocol | yes | |
| Connect GitHub, see everyone’s runners | yes | |
| See private repos they weren’t added to | no | no |
Admins don’t see private repositories unless they add themselves as a collaborator, which shows in the repo’s collaborator list. Whoever runs the node can still read its disk.
The first admin#
A new node prints a setup link to its log on every start until it has an admin. Whoever opens it picks the first admin’s handle and password. See Create the first admin.
Invite people#
Admins invite people from the People page (account menu → People):
- Under Invite someone, type a Handle and choose Member or Admin.
- Click Create invite link.
- Send the link to the person. It works once, for 24 hours, and isn’t shown again.
They open it, set a password of at least 12 characters, and click Set password and sign in. Moru sends no email, so the link reaches them however you choose.
The same from the command line, which prints the link:
moru-node create-user jon # a member
moru-node create-user mira --admin # an admin create-user uses MORU_PUBLIC_URL (or --url) for the link’s address. In the container image that’s already set.
Each person in the list shows whether their invite is pending, how many sessions and access tokens they have, and their DID. Make admin and Make member change the role; the person is signed out when it changes.
Handles and organization names share one namespace, so a handle can’t be an existing organization’s name.
Passwords and sessions#
- Changing a password: in Account, under Password.
- Forgotten passwords: an admin clicks Reset link next to the person on the People page. Their password and sessions stop working, and the new link lets them set a password. There’s no self-service reset.
- Every admin locked out: run
moru-node create-user mira --reseton the node. It prints a new link for that account and revokes its password and tokens. - Sessions last 12 hours. Sign out everywhere in Account ends all of a person’s sessions.
- Failed sign-ins: after 5 failed passwords for one handle from one address, that address is locked out for that handle for 15 minutes. Behind a reverse proxy, set
MORU_TRUSTED_PROXIESso the node sees each client’s address. See Configuration.
For git over HTTPS, people use an access token from Account → Access tokens for git as the password, with any user name. A token lasts up to 366 days (90 by default) and can be limited to one repo. A token reaches only what its person can read or write at the time of each request.
Tokens for scripts#
moru-node create-user-token prints a token for a person, for scripts and tests:
moru-node create-user-token mira --ttl 7d It also prints a sign-in link. If the handle has no account, the command creates one as an admin, with a did:key. To give someone a normal account, use create-user instead.
Sign in with AT Protocol#
People can sign in with their own AT Protocol account, as long as its DID is a did:plc (did:web identities can’t sign in). On the sign-in page, they enter their handle or DID under Sign in with your AT Protocol account and approve the request at their PDS.
Once they’re let in (see who may join), the sign-in writes one record, com.moruforge.host.binding, to their AT Protocol repo. It authorizes this node’s host to sign for them. The node creates a member account for their DID, and keeps nothing of the OAuth session: it revokes it once the record is written.
What the node needs for this:
- An
httpspublic URL. With one, the node is a confidential OAuth client. It serves its client metadata at/oauth-client-metadata.json, which PDSs must be able to fetch, and signs withkeys/oauth-client.key, which it makes on first use. Back that key up with the others. - Without
https, the node acts as a loopback client, which AT Protocol allows for development only. The PDS sends the browser back tohttp://127.0.0.1:<port>/api/v0/atproto/callback, where the port is the one the node listens on, whateverMORU_PUBLIC_URLsays. So sign in from a browser on the node’s own machine, athttp://127.0.0.1:<port>. A node on a LAN over plain HTTP can’t offer AT Protocol sign-in. - Outbound HTTPS. People’s DIDs resolve at the PLC directory (
MORU_PLC_URL, by defaulthttps://plc.directory). Sign-in fetches whatever a person’s DID document and handle point to, but onlyhttpsURLs at public addresses, with no proxy and no redirects.
Limits: each client address may start 10 sign-ins per 15 minutes, and at most 16 run at once.
Who may join#
New people on the People page sets what happens when someone signs in with an AT Protocol account the node hasn’t seen:
- Ask to join (the default): their first sign-in files a request and writes nothing to their account. Admins see a badge in the header and on People, and click Approve or Decline. An approved person signs in again to get their account. A declined person is told so each time they sign in, until an admin approves them or clicks Forget (then they may ask again).
- Open: anyone with an AT Protocol account gets a member account the first time they sign in.
- Closed: new AT Protocol identities are refused. People who already have an account still sign in, and approved requests still get in.
Invites and linking work in every mode. Moru doesn’t notify people when you decide, so tell them.
Linking a password account#
Someone with a password account can link it to their AT Protocol identity in Account, under Link your AT Protocol identity: they enter their AT Protocol handle or DID and their current password, then approve at their PDS. Their handle and password on the node stay the same. Their identity becomes the AT Protocol DID, and repos record that the old did:key is now the new one, so their history moves with them.
Host identity#
Every node signs as part of a host: the identity that certifies the node’s key in each repo, so signatures on changes, comments and attestations can be checked anywhere, offline. host.json in the data directory records which kind of host the node has. There are two:
key, offline (the default for a new data directory). The host is the node key’s owndid:key. Nothing is registered anywhere. It can’t be rotated, and can’t be moved to another host with trust intact.plc, adid:plcregistered with the PLC directory. On the firstservethe node makes two keys inkeys/host/(a rotation key and a signing key) and registers a DID namingMORU_PUBLIC_URLas itsmoruservice. It needsMORU_PUBLIC_URL, and won’t start if the directory can’t be reached the first time. Later starts refresh the DID’s log, and keep the cached one if the directory is down. Other commands never contact the directory.
To use plc, set it for the very first start:
MORU_IDENTITY=plc MORU_PUBLIC_URL=https://moru.example.com moru-node --data /var/lib/moru serve moru-node host prints the host’s DID, its kind and the node’s DID, and for a did:plc host its current signing key. --refresh fetches the DID’s log first, as serve does. People see the host on their Account page.
keys/host/ and host.json are the host. Back them up with the rest of the data directory (moru-node backup includes them), and guard keys/host/rotation.key above everything: whoever holds it controls the DID. Change the DID document rarely, for a key rotation or a new public URL, not as routine: each change adds a snapshot to every repo the node writes to.
If you lose the host identity#
Restore host.json, keys/host/ and keys/node.key from a backup whenever you can. If you can’t, the node makes a new host on its next start, with a new DID:
- Old signatures still load. The old host’s record stays in every repo that has it.
- People who signed in with AT Protocol have to sign in again, so their PDS authorizes the new host.
- People with password accounts sign with their own keys and aren’t affected, as long as
keys/users/survived. - Attestations signed with the old node key are untrusted until you add the old host’s DID, or the old node key, to
trusted-attesters.json. Until then, merge rules that depend on them refuse the change. See Provenance.