Document how to setup conduit

[meenzen]

There is currently no documentation on how to properly setup conduit.

Conduit support is experimental but we should at least provide some basic documentation.

Proposal: Add documentation for the most common tasks

This is what i've come up with so far:

Configuring Conduit (optional, experimental)

To use Conduit instead of Synapse enable it in vars.yml:

matrix_homeserver_implementation: conduit

Creating the admin account

Conduit automatically makes the first user an admin. To create the account, simply register using a matrix client like Element.

Disabling registration

By default anyone can create an account on your homeserver. After creating the admin account you can disable it in vars.yml:

matrix_conduit_allow_registration: false

You can still create users using the admin command [conduit docs not available yet]

Configuring bridges / appservices

Automatic appservice setup is currently unsupported when using conduit. After setting up the service as usual you may notice that it is unable to start.

You will have to manually register it using the the register-appservice command.

Find the registration.yaml in the /matrix directory, for example /matrix/mautrix-signal/bridge/registration.yaml, then pass the content to conduit:

@conduit:your.server.name: register-appservice
```
as_token: <token>
de.sorunome.msc2409.push_ephemeral: true
hs_token: <token>
id: signal
namespaces:
  aliases:
  - exclusive: true
    regex: ^#signal_.+:example\.org$
  users:
  - exclusive: true
    regex: ^@signal_.+:example\.org$
  - exclusive: true
    regex: ^@signalbot:example\.org$
rate_limited: false
sender_localpart: _bot_signalbot
url: http://matrix-mautrix-signal:29328
```

[spantaleev]

Homeserver registration should not be public by default. I've addressed this in caebb7be0b2cd02a.

Is there really no better way to create Conduit users than to use public registration?

[meenzen]

As far as I know the only other option right now is using the admin command:

@conduit:your.server.name: create-user <username>

See: https://gitlab.com/famedly/conduit/-/issues/276 https://gitlab.com/famedly/conduit/-/merge_requests/354

[meenzen]

As a temporary workaround it should be possible to script user creation like this:

1. Disable public server access (maybe shut down the proxy?)
2. Restart Conduit with public registration enabled
3. Register user via curl (see: https://matrix.org/docs/guides/client-server-api#registration)
4. Restart Conduit with public registration disabled
5. Enable public server access

[spantaleev]

Our instructions could be to:

1. Use matrix_conduit_allow_registration: true in your vars.yml the first time around, temporarily
2. Run --tags=setup-all,start
3. Create your first user via Element or whatever client that supports creating users
4. Get rid of matrix_conduit_allow_registration: true from your vars.yml
5. Run --tags=setup-conduit,start
6. You can now use your server safely. Additional users can be created by messaging the internal Conduit bot

[qeshi]

I just got Matrix up and running with conduit thanks to this issue :)

I tried ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user

And it didn't complain but I couldn't log in with the user I tried to create so it was a bit confusing.