Run your own relay
In this tutorial you run a MOQtail relay on your machine. You then use the Rust CLI client to publish a test track to it and to subscribe to that track, first over WebTransport and then over raw QUIC.
What you need
- mkcert, to make a certificate.
- Docker. The relay image is built for
linux/amd64; on other machines, step 2 shows how to run the relay from source. - Git and a recent stable Rust toolchain, to build the CLI client.
You use three terminals: one for the relay, one for the publisher and one for the subscriber.
1. Make a certificate
Make a folder for the tutorial, and a certificate in it:
mkdir moqtail-tutorial && cd moqtail-tutorial
mkcert -install
mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1mkcert -install creates a local certificate authority and adds it to your system's trust store. It may ask for your password. The second command makes cert.pem and key.pem, valid for localhost. The CLI client trusts the system's store, so it accepts this certificate.
2. Start the relay
In the moqtail-tutorial folder, run the relay image:
docker run --rm \
--user "$(id -u):$(id -g)" \
-p 4433:4433/udp \
-v "$PWD/cert.pem:/certs/cert.pem:ro" \
-v "$PWD/key.pem:/certs/key.pem:ro" \
ghcr.io/moqtail/relay:latestmkcert made key.pem readable only by you, so --user runs the relay as you. The last line the relay prints shows where it listens (timestamps are left out on this page):
INFO relay::server: moqtail/0.19.0+7412a2f is running on 1 UDP socket(s) -- WebTransport clients: https://localhost:4433 Raw QUIC clients: moqt://localhost:4433The relay takes WebTransport and raw QUIC on the same UDP port, 4433. A warning about UDP socket buffers does not matter here. Leave the relay running.
If you can't run the image, do step 3 first, then start the relay from source in the moqtail folder with cargo run -p relay -- --cert-file ../cert.pem --key-file ../key.pem.
3. Build the CLI client
In a second terminal, in the moqtail-tutorial folder, get the code and build the client:
git clone https://github.com/moqtail/moqtail.git
cd moqtail
cargo build -p clientThe first build takes a few minutes. The client, target/debug/client, publishes, subscribes to and fetches test objects, over either transport.
4. Publish a track
In the same terminal:
./target/debug/client -c publish --server moqt://localhost:4433The client connects over WebTransport, its default, and publishes the track demo in the namespace moqtail. It sends one object a second, ten objects to a group, each with 1200 bytes of test payload:
INFO client::publisher: Track published
INFO client::publisher: Sent object: group=0, subgroup=0, object=0, size=1200 bytes
INFO client::publisher: Sent object: group=0, subgroup=0, object=1, size=1200 bytesLeave it running.
5. Subscribe over WebTransport
In a third terminal, go to the moqtail folder and subscribe to the track for five seconds:
./target/debug/client -c subscribe --server moqt://localhost:4433 --duration 5The subscriber asks the relay for moqtail/demo, starting with the next object. Each object the publisher sends arrives through the relay:
INFO client::subscriber: Subscribed: track=demo track_alias=0 track_properties=[]
INFO client::subscriber: Received object 1: subscription=req=0(demo) group=0, object=2, subgroup=Some(0), priority=128, seq=OK
INFO client::subscriber: Received object 2: subscription=req=0(demo) group=0, object=3, subgroup=Some(0), priority=128, seq=OK
...
INFO client::subscriber: Subscriber finished: received=5, fill=0, errors=0, gaps=0, duplicates=0, filter_violations=0gaps=0 means that every object arrived, in order. A StreamClosed error while the client closes its connection is expected.
In the relay's terminal, a line for each client names the transport it came over:
INFO relay::server::session: New session: connection_id=1711044711 transport=webtransport remote=[::ffff:127.0.0.1]:509996. Subscribe over raw QUIC
Run the subscriber again, with --transport quic:
./target/debug/client -c subscribe --server moqt://localhost:4433 --transport quic --duration 5The objects arrive as before. This time the relay's log says transport=quic. The relay took both connections on the same port, and it forwards what the WebTransport publisher sends to the raw QUIC subscriber. The publisher takes --transport quic too.
7. Stop
Press Ctrl-C in the publisher's terminal, then in the relay's. The relay prints Ctrl-C received, exiting..., and --rm removes the container.
The client has more commands: publish-namespace, subscribe-namespace, subscribe-tracks and fetch. apps/client/README.md lists them with their flags.
What you built
You made a certificate your machine trusts, ran a relay that serves WebTransport and raw QUIC on one UDP port, and passed a track from a publisher to subscribers over both transports.
Next steps
- Build a live player that runs in the browser. Before you point it at your relay, let the browser accept your mkcert certificate: see Set up TLS certificates.
- Configure the relay: the cache, subscriber limits, logs and qlog traces.
- Monitor the relay through its HTTP API and metrics.