From 985129732316a3950c287780fffa0ee7c523b2a3 Mon Sep 17 00:00:00 2001 From: epoberezkin Date: Fri, 17 Jul 2026 14:40:29 +0000 Subject: [PATCH] deploy: 42acafc7cfb018a7ef4f0ac078fb1812d72825f2 --- docs/android.html | 4 + docs/business.html | 4 + docs/chat-relay.html | 1176 +++++++++++++++++++++++++ docs/cli.html | 4 + docs/code_of_conduct.html | 4 + docs/contributing.html | 4 + docs/directory.html | 4 + docs/glossary.html | 4 + docs/guide/app-settings.html | 4 + docs/guide/audio-video-calls.html | 4 + docs/guide/channel-webpage.html | 4 + docs/guide/chat-profiles.html | 4 + docs/guide/making-connections.html | 4 + docs/guide/managing-data.html | 4 + docs/guide/privacy-security.html | 4 + docs/guide/readme.html | 4 + docs/guide/register-simplex-name.html | 4 + docs/guide/secret-groups.html | 4 + docs/guide/send-messages.html | 4 + docs/protocol/channels-overview.html | 4 + docs/protocol/channels-protocol.html | 4 + docs/protocol/names-overview.html | 4 + docs/protocol/simplex-chat.html | 4 + docs/server.html | 4 + docs/simplex.html | 4 + docs/themes.html | 4 + docs/trademark.html | 4 + docs/translations.html | 4 + docs/webrtc.html | 4 + docs/why.html | 4 + docs/xftp-server.html | 4 + downloads/index.html | 4 + faq/index.html | 4 + reproduce/index.html | 4 + security/index.html | 4 + transparency/index.html | 4 + 36 files changed, 1316 insertions(+) create mode 100644 docs/chat-relay.html diff --git a/docs/android.html b/docs/android.html index dd5ba7b490..a335bd9a7c 100644 --- a/docs/android.html +++ b/docs/android.html @@ -782,6 +782,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 9b6f562973..069ebea24e 100644 --- a/docs/business.html +++ b/docs/business.html @@ -644,6 +644,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..188fd30398 --- /dev/null +++ b/docs/chat-relay.html @@ -0,0 +1,1176 @@ + + + + + + + + + + + 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.

    +
    +
    +
    +
    +
    + + + + + + + + + + \ No newline at end of file diff --git a/docs/cli.html b/docs/cli.html index 6ae7ab8280..bbf51bbd30 100644 --- a/docs/cli.html +++ b/docs/cli.html @@ -782,6 +782,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 d899831174..06d5622fcc 100644 --- a/docs/code_of_conduct.html +++ b/docs/code_of_conduct.html @@ -644,6 +644,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 3d53f605c9..025eff4fc0 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -782,6 +782,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 569f62a73d..eb618e8a64 100644 --- a/docs/directory.html +++ b/docs/directory.html @@ -543,6 +543,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 7184d9b82f..4ca9b76011 100644 --- a/docs/glossary.html +++ b/docs/glossary.html @@ -644,6 +644,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 870fbeee3f..865b98e9f1 100644 --- a/docs/guide/app-settings.html +++ b/docs/guide/app-settings.html @@ -644,6 +644,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 b76a2ef835..418b0cc456 100644 --- a/docs/guide/audio-video-calls.html +++ b/docs/guide/audio-video-calls.html @@ -644,6 +644,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 911b20e412..521d037c87 100644 --- a/docs/guide/channel-webpage.html +++ b/docs/guide/channel-webpage.html @@ -644,6 +644,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 0d71a862da..8c3338c0f3 100644 --- a/docs/guide/chat-profiles.html +++ b/docs/guide/chat-profiles.html @@ -543,6 +543,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 4e163bdf9b..c4bad548c8 100644 --- a/docs/guide/making-connections.html +++ b/docs/guide/making-connections.html @@ -644,6 +644,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 a22fec1482..05001df286 100644 --- a/docs/guide/managing-data.html +++ b/docs/guide/managing-data.html @@ -644,6 +644,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 5f7c6dd35b..8458eab586 100644 --- a/docs/guide/privacy-security.html +++ b/docs/guide/privacy-security.html @@ -543,6 +543,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 e519c15f22..e37f83a231 100644 --- a/docs/guide/readme.html +++ b/docs/guide/readme.html @@ -644,6 +644,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 e63dfdb6da..d326c99197 100644 --- a/docs/guide/register-simplex-name.html +++ b/docs/guide/register-simplex-name.html @@ -644,6 +644,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 1d74ca1376..2bf9a150c1 100644 --- a/docs/guide/secret-groups.html +++ b/docs/guide/secret-groups.html @@ -644,6 +644,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 ca810b2a07..8ccb524d81 100644 --- a/docs/guide/send-messages.html +++ b/docs/guide/send-messages.html @@ -644,6 +644,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 3ac1cabeaf..914de1d914 100644 --- a/docs/protocol/channels-overview.html +++ b/docs/protocol/channels-overview.html @@ -644,6 +644,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 7f525d11bd..48d0843605 100644 --- a/docs/protocol/channels-protocol.html +++ b/docs/protocol/channels-protocol.html @@ -644,6 +644,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 1433ef68f4..7c4357ce1f 100644 --- a/docs/protocol/names-overview.html +++ b/docs/protocol/names-overview.html @@ -644,6 +644,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 f7dfc501bd..8f25c2924d 100644 --- a/docs/protocol/simplex-chat.html +++ b/docs/protocol/simplex-chat.html @@ -644,6 +644,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 30c0a6fa01..edfdec5047 100644 --- a/docs/server.html +++ b/docs/server.html @@ -782,6 +782,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 ef96f359a0..42fa1b0134 100644 --- a/docs/simplex.html +++ b/docs/simplex.html @@ -782,6 +782,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 612c050283..e7016b1fb0 100644 --- a/docs/themes.html +++ b/docs/themes.html @@ -644,6 +644,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 4d9dada606..256cb664da 100644 --- a/docs/trademark.html +++ b/docs/trademark.html @@ -644,6 +644,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 5f6c35d27b..fd9b49a42a 100644 --- a/docs/translations.html +++ b/docs/translations.html @@ -782,6 +782,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 2bf2694957..f216702242 100644 --- a/docs/webrtc.html +++ b/docs/webrtc.html @@ -782,6 +782,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 6bd54b7b3d..f2a6c016b8 100644 --- a/docs/why.html +++ b/docs/why.html @@ -644,6 +644,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 c762809911..f448d078e4 100644 --- a/docs/xftp-server.html +++ b/docs/xftp-server.html @@ -644,6 +644,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 1c26d92266..04b2d81e48 100644 --- a/downloads/index.html +++ b/downloads/index.html @@ -644,6 +644,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 f76ecb4f11..93a31fc897 100644 --- a/faq/index.html +++ b/faq/index.html @@ -644,6 +644,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 1df45051c2..d4ce43606a 100644 --- a/reproduce/index.html +++ b/reproduce/index.html @@ -644,6 +644,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 82d356fa3d..68ef8d57fa 100644 --- a/security/index.html +++ b/security/index.html @@ -644,6 +644,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 14745d4849..f58efc4d0b 100644 --- a/transparency/index.html +++ b/transparency/index.html @@ -644,6 +644,10 @@ window.addEventListener('click',(e)=>{ Hosting your own XFTP Server +
  • + Hosting your own Chat Relay +
  • +
  • Download SimpleX apps