diff --git a/docs/android.html b/docs/android.html index c50e8f56c0..52434ca2fd 100644 --- a/docs/android.html +++ b/docs/android.html @@ -784,6 +784,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/business.html b/docs/business.html index 6595b6d1c9..d857396a72 100644 --- a/docs/business.html +++ b/docs/business.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/chat-relay.html b/docs/chat-relay.html new file mode 100644 index 0000000000..693aa9a3c8 --- /dev/null +++ b/docs/chat-relay.html @@ -0,0 +1,1178 @@ + + + + + + + + + + + Hosting your own Chat Relay + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + +
    + + + + +
    +
    +
    + +
    + + + + +

    Hosting your own Chat Relay

    +

    Chat relays are used to deliver channel messages in SimpleX Network. Read more about channels in this whitepaper and this blog post.

    +

    A chat relay is the SimpleX Chat CLI (simplex-chat) running in relay mode (--relay). It has its own profile (a display name and a picture), its own address, and in addition to delivering messages, it can generate data for web previews of the channels it delivers.

    +

    This guide explains how to set up a chat relay on a Linux server, how to run it, and (optionally) how to configure Caddy to serve data for channel web previews.

    +
    +

    Please note: This guide applies only to SimpleX Chat v7.0.0-beta.4 and later.

    +
    +

    Table of Contents

    + +

    Install the CLI

    +

    The relay is the standard simplex-chat CLI binary. Install or update it with the install script:

    +
    curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/stable/install.sh | bash
+
    +

    Other options (manual binary download, building from source) are in the CLI guide.

    +

    Copy the installed simplex-chat binary to /usr/local/bin/simplex-chat-relay. The guide uses that name so the relay is separate from any interactive simplex-chat you also run on the server.

    +

    Create a dedicated user for the relay (called relay below), so it does not run as root and keeps its database in one place:

    +
    sudo useradd -m relay
+
    +

    The useradd -m flag creates its home directory /home/relay, where the guide keeps the database and picture. Run the relay commands (the -e commands below) as this user, for example with sudo -u relay ...; run the systemd and Caddy steps as root.

    +

    Run the relay

    +

    Run the relay as a systemd service. With --headless it starts without any interactive prompts. It creates its profile and address on the first start, and writes its output to the journal.

    +

    Create a run script /usr/local/bin/relay-run:

    +
    #!/bin/sh
+exec /usr/local/bin/simplex-chat-relay \
+  --relay \
+  --headless \
+  --user-display-name "My Relay" \
+  --user-image-file /home/relay/avatar.png \
+  -d /home/relay/relay
+
    +
    chmod +x /usr/local/bin/relay-run
+
    +

    Create /etc/systemd/system/simplex-relay.service:

    +
    [Unit]
+Description=SimpleX Chat relay
+After=network.target
+
+[Service]
+User=relay
+ExecStart=/usr/local/bin/relay-run
+Restart=always
+StandardInput=null
+
+[Install]
+WantedBy=multi-user.target
+
    +

    Enable and start it:

    +
    systemctl daemon-reload
+systemctl enable --now simplex-relay
+
    +

    The first start creates the relay profile (with the given name and picture) and its address; later starts reuse them. Both are written to the journal:

    +
    Current user: My Relay
+Chat relay address is created:
+https://smp4.simplex.im/r#73iEnnvCqPTVGArCAWUcRaj5hxRb7TbPCSZ2JY2VjCQ
+
    +

    Relay options

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OptionPurpose
    --relayRun as a chat relay. Required.
    --headlessDon't ask interactive questions; create the profile and address automatically. On first start it also needs --user-display-name.
    --user-display-name NAMEThe relay's display name. Creates the profile on first start; on later starts it must match the existing profile.
    --user-image-file FILEThe relay's picture, from a .png, .jpg or .jpeg file. Applied only when the profile is created; ignored afterwards.
    --relay-address-server SERVERCreate the relay address on a specific SMP server, e.g. smp://<fingerprint>@smp.example.com. By default a preset server is used. Requires --relay.
    +

    Get the relay address

    +

    The address is created and logged on the first start. Read it from the journal at any time:

    +
    journalctl -u simplex-relay | grep -A1 "address is created"
+
    +

    Run relay commands

    +

    The service runs headless, so there is no attached terminal to type into. To run a one-off command, stop the service, run the command against the relay's database with -e, then start it again. For example, to change the picture (--user-image-file only sets it when the profile is first created):

    +
    systemctl stop simplex-relay
+simplex-chat-relay -d /home/relay/relay -e "/set profile image file /home/relay/new-avatar.png"
+systemctl start simplex-relay
+
    +

    Channel web previews

    +

    Chat relays can render recent messages of its public channels as JSON files, which can be served over HTTPS using a web server to create channel web previews. This is optional.

    +

    Relay web options

    +

    Add these to the run script (--relay-web-domain and --relay-web-dir must be given together):

    +
      --relay-web-domain relay.example.com \
+  --relay-web-dir /var/www/relay-web-channels/channel \
+  --relay-web-cors-file /var/www/relay-web-channels/cors.conf \
+  --relay-web-interval 30 \
+
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OptionPurpose
    --relay-web-domain DOMAINDomain the previews are served from.
    --relay-web-dir DIRDirectory the relay writes channel JSON files to.
    --relay-web-cors-file FILEFile the relay writes the generated Caddy CORS config to.
    --relay-web-interval SECONDSHow often previews are regenerated (default 300).
    --relay-web-item-count COUNTRecent messages per channel preview (default 50).
    +

    Create the web directory, owned by the relay user:

    +
    mkdir -p /var/www/relay-web-channels/channel
+chmod 0755 /var/www/relay-web-channels
+chown -R relay:relay /var/www/relay-web-channels
+
    +

    Restart the relay so the new flags take effect:

    +
    systemctl restart simplex-relay
+
    +

    Serve the previews with Caddy

    +

    This section uses Caddy as the web server. Install it (Debian/Ubuntu):

    +
    sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl &&\
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg &&\
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list &&\
+sudo apt update && sudo apt install caddy
+
    +

    The relay writes files to /var/www/relay-web-channels/channel/<id>.json. Serve them, and import the relay's generated CORS rules, in your Caddyfile:

    +
    relay.example.com {
+  encode zstd gzip
+
+  handle /channel/* {
+    root * /var/www/relay-web-channels    # files resolve to .../channel/<id>.json
+    file_server
+    import /etc/caddy/simplex-cors.conf
+  }
+}
+
    +

    Keep root at the parent directory with a non-stripping handle. That is what makes /channel/<id>.json resolve to .../channel/<id>.json. Do not point root at the channel subdirectory: the relay's generated CORS matchers are /channel/*.json, which only match when the prefix is kept.

    +
    touch /etc/caddy/simplex-cors.conf      # so the import doesn't fail before the first write
+usermod -aG relay caddy                 # let caddy read the relay user's files
+systemctl restart caddy                 # restart (not reload) to pick up the group
+
    +

    Reload CORS automatically

    +

    The relay updates its CORS file as channels change. Copy it into Caddy's config and reload Caddy whenever it changes.

    +

    Create /usr/local/bin/simplex-cors-sync.sh:

    +
    #!/bin/sh
+set -eu
+SRC=/var/www/relay-web-channels/cors.conf
+DST=/etc/caddy/simplex-cors.conf
+[ -f "$SRC" ] || exit 0
+cmp -s "$SRC" "$DST" 2>/dev/null && exit 0
+install -m 0644 "$SRC" "$DST"
+systemctl reload caddy
+logger -t simplex-cors "reloaded caddy"
+
    +

    Create /etc/systemd/system/simplex-cors-sync.service:

    +
    [Unit]
+Description=Sync SimpleX relay CORS config to Caddy
+StartLimitIntervalSec=30
+StartLimitBurst=10
+[Service]
+Type=oneshot
+ExecStartPre=/bin/sleep 2
+ExecStart=/usr/local/bin/simplex-cors-sync.sh
+
    +

    Create /etc/systemd/system/simplex-cors-sync.path to run the service whenever the relay's CORS file changes:

    +
    [Unit]
+Description=Watch SimpleX relay CORS config
+After=caddy.service
+[Path]
+PathChanged=/var/www/relay-web-channels/cors.conf
+Unit=simplex-cors-sync.service
+[Install]
+WantedBy=multi-user.target
+
    +

    Enable it:

    +
    chmod +x /usr/local/bin/simplex-cors-sync.sh
+systemctl daemon-reload
+systemctl enable --now simplex-cors-sync.path
+
    +

    Verify

    +
    systemctl status simplex-cors-sync.path              # active (waiting)
+ls /var/www/relay-web-channels/channel               # a JSON file appears once a public channel renders
+curl -sI https://relay.example.com/channel/<id>.json | grep -i access-control
+
    +

    The curl should return access-control-* headers, and the channel link should open a web preview in a browser.

    +
    +
    +
    +
    +
    + + +
    +
    +
    +
    + logo + + +
    +
    + + Why we are building it + + + About & Contact us + + + Privacy Policy + + + Join team + + + Donate + + +
    +
    + + SimpleX Whitepaper + + + + SimpleX Chat protocol + + + + Terminal CLI + + + + SimpleX bots API + + +
    +
    +
    + + +
    + © 2020-2025 SimpleX Chat | Open-Source Project +
    +
    + + + + + + + \ No newline at end of file diff --git a/docs/cli.html b/docs/cli.html index 49d9879062..2bdc691ed2 100644 --- a/docs/cli.html +++ b/docs/cli.html @@ -784,6 +784,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/code_of_conduct.html b/docs/code_of_conduct.html index fe3f22e5cb..c53d37b142 100644 --- a/docs/code_of_conduct.html +++ b/docs/code_of_conduct.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/contributing.html b/docs/contributing.html index 61ec2689bf..620b41bdb9 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -784,6 +784,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/directory.html b/docs/directory.html index dcd81d995b..88fb83ec93 100644 --- a/docs/directory.html +++ b/docs/directory.html @@ -545,6 +545,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/glossary.html b/docs/glossary.html index e5dfe0a969..c0bdd39b3a 100644 --- a/docs/glossary.html +++ b/docs/glossary.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/app-settings.html b/docs/guide/app-settings.html index 5594e0b273..f4bc99c56a 100644 --- a/docs/guide/app-settings.html +++ b/docs/guide/app-settings.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/audio-video-calls.html b/docs/guide/audio-video-calls.html index 70f6a4a5cd..fe5200f66b 100644 --- a/docs/guide/audio-video-calls.html +++ b/docs/guide/audio-video-calls.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/channel-webpage.html b/docs/guide/channel-webpage.html index 72a95de359..85587c05e4 100644 --- a/docs/guide/channel-webpage.html +++ b/docs/guide/channel-webpage.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/chat-profiles.html b/docs/guide/chat-profiles.html index 9b4423e2aa..4d8fd46d72 100644 --- a/docs/guide/chat-profiles.html +++ b/docs/guide/chat-profiles.html @@ -545,6 +545,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/making-connections.html b/docs/guide/making-connections.html index 8b7e63434e..af006d9c4e 100644 --- a/docs/guide/making-connections.html +++ b/docs/guide/making-connections.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/managing-data.html b/docs/guide/managing-data.html index dec2d2dfc5..6a7cad06ed 100644 --- a/docs/guide/managing-data.html +++ b/docs/guide/managing-data.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/privacy-security.html b/docs/guide/privacy-security.html index 662afc23f6..7f9beeaf5d 100644 --- a/docs/guide/privacy-security.html +++ b/docs/guide/privacy-security.html @@ -545,6 +545,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/readme.html b/docs/guide/readme.html index 9367fef209..5fbb6033be 100644 --- a/docs/guide/readme.html +++ b/docs/guide/readme.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/register-simplex-name.html b/docs/guide/register-simplex-name.html index b47a58da61..0f8635ceac 100644 --- a/docs/guide/register-simplex-name.html +++ b/docs/guide/register-simplex-name.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/secret-groups.html b/docs/guide/secret-groups.html index fb31f202fb..e7be92ee76 100644 --- a/docs/guide/secret-groups.html +++ b/docs/guide/secret-groups.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/guide/send-messages.html b/docs/guide/send-messages.html index 321d8d7918..0231e5618e 100644 --- a/docs/guide/send-messages.html +++ b/docs/guide/send-messages.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/protocol/channels-overview.html b/docs/protocol/channels-overview.html index 5c493d6203..d1778b93fc 100644 --- a/docs/protocol/channels-overview.html +++ b/docs/protocol/channels-overview.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/protocol/channels-protocol.html b/docs/protocol/channels-protocol.html index cb42b1681d..c7c4d82133 100644 --- a/docs/protocol/channels-protocol.html +++ b/docs/protocol/channels-protocol.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/protocol/names-overview.html b/docs/protocol/names-overview.html index 04fe7d1c0e..aae6162f78 100644 --- a/docs/protocol/names-overview.html +++ b/docs/protocol/names-overview.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/protocol/simplex-chat.html b/docs/protocol/simplex-chat.html index 0a70ab7b92..0f89bcc3e4 100644 --- a/docs/protocol/simplex-chat.html +++ b/docs/protocol/simplex-chat.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/server.html b/docs/server.html index 985e013458..7a846346f4 100644 --- a/docs/server.html +++ b/docs/server.html @@ -784,6 +784,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/simplex.html b/docs/simplex.html index add6818f79..4bb2f16a2c 100644 --- a/docs/simplex.html +++ b/docs/simplex.html @@ -784,6 +784,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/themes.html b/docs/themes.html index b426fea0f6..a082acf0c1 100644 --- a/docs/themes.html +++ b/docs/themes.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/trademark.html b/docs/trademark.html index 3d4590d66d..6376e92a99 100644 --- a/docs/trademark.html +++ b/docs/trademark.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/translations.html b/docs/translations.html index 76d6a9bcf0..e5428ad7ad 100644 --- a/docs/translations.html +++ b/docs/translations.html @@ -784,6 +784,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/webrtc.html b/docs/webrtc.html index 1336ed9660..88b5414491 100644 --- a/docs/webrtc.html +++ b/docs/webrtc.html @@ -784,6 +784,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/why.html b/docs/why.html index e1b0d4a008..e69bd26888 100644 --- a/docs/why.html +++ b/docs/why.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/docs/xftp-server.html b/docs/xftp-server.html index e4d90286f6..fb1ff117d3 100644 --- a/docs/xftp-server.html +++ b/docs/xftp-server.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/downloads/index.html b/downloads/index.html index d0d3a67c8e..ca2b81ec1c 100644 --- a/downloads/index.html +++ b/downloads/index.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/faq/index.html b/faq/index.html index 0adb9d4c7c..51eef344ea 100644 --- a/faq/index.html +++ b/faq/index.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/reproduce/index.html b/reproduce/index.html index e7764b4649..7603e0485f 100644 --- a/reproduce/index.html +++ b/reproduce/index.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/security/index.html b/security/index.html index 0aa0cee145..4e5f45c94a 100644 --- a/security/index.html +++ b/security/index.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps
    • diff --git a/transparency/index.html b/transparency/index.html index dda577cacf..a6d7c0c6c9 100644 --- a/transparency/index.html +++ b/transparency/index.html @@ -646,6 +646,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
    • +
  • Download SimpleX apps