mirror of https://github.com/simplex-chat/simplexmq.git synced 2026-03-29 10:10:06 +00:00

Files

Evgeny @ SimpleX Chat 1db93b936d corrections

2026-03-14 13:54:41 +00:00

8.0 KiB

Raw Permalink Blame History

SimpleX Routers: Deployment and Configuration

SimpleX routers are the network infrastructure of the SimpleX Network. They accept, buffer, and deliver data packets between endpoints. Each router operates independently and can be run by any party on standard computing hardware.

This document covers deployment and advanced configuration. For an overview of the router architecture and trust model, see the SimpleX Network overview. For internal architecture diagrams (thread topology, command processing flows), see spec/routers.md.

SMP Router

The SMP router provides messaging queues - unidirectional, ordered sequences of fixed-size packets (16,384 bytes each). It implements the SimpleX Messaging Protocol. For architecture and module specs, see SMP Router.

Advanced configuration

smp-server.ini is created during initialization and controls all runtime behavior.

Message persistence: when store log is enabled (enable: on), the server saves undelivered messages on exit and restores them on start. This only works with SIGINT (keyboard interrupt); SIGTERM does not trigger message saving. The restore_messages setting can be used to override this behavior independently of the store log setting.

Tor onion addresses: the server can have both a public hostname and an onion hostname, allowing two users to connect when only one is using Tor. Configure as: smp://<fingerprint>@<public_hostname>,<onion_hostname>. See scripts/tor/ for setup instructions.

Running on MacOS

SMP server requires OpenSSL for initialization. MacOS may ship LibreSSL instead, which doesn't support the required algorithms.

openssl version

If it says "LibreSSL", install OpenSSL:

brew update
brew install openssl
echo 'PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"' >> ~/.zprofile
. ~/.zprofile

XFTP Router

The XFTP router accepts and delivers data packets over HTTP/2 - individually addressed blocks in fixed sizes (64KB, 256KB, 1MB, 4MB). It implements the XFTP protocol. Data packets are used for larger payload delivery (files, media) where SMP queue packet sizes would be inefficient. The use of HTTP/2 simplifies browser integration. For architecture and module specs, see XFTP Router.

Initialize with xftp-server init and configure storage quota in xftp-server.ini.

NTF Router

The NTF router bridges SimpleX Network to platform push notification services (APNS). It implements the Push Notifications protocol. Mobile clients register push tokens with the NTF router, which subscribes to their SMP queues and sends push notifications when messages arrive. The push notification contains only a notification ID, not message content. For architecture and module specs, see NTF Router.

Initialize with ntf-server init and configure APNS credentials in ntf-server.ini.

Deployment methods

All routers require openssl as a runtime dependency for certificate generation during initialization:

# Ubuntu
apt update && apt install openssl

Docker (prebuilt images)

Prebuilt images are available from Docker Hub.

Create directories for persistent configuration:

mkdir -p $HOME/simplex/{xftp,smp}/{config,logs} && mkdir -p $HOME/simplex/xftp/files

Run:

SMP router - change your_ip_or_domain; -e "PASS=password" is optional:

docker run -d \
    -e "ADDR=your_ip_or_domain" \
    -e "PASS=password" \
    -p 5223:5223 \
    -v $HOME/simplex/smp/config:/etc/opt/simplex:z \
    -v $HOME/simplex/smp/logs:/var/opt/simplex:z \
    simplexchat/smp-server:latest

XFTP router - change your_ip_or_domain and maximum_storage:

docker run -d \
    -e "ADDR=your_ip_or_domain" \
    -e "QUOTA=maximum_storage" \
    -p 443:443 \
    -v $HOME/simplex/xftp/config:/etc/opt/simplex-xftp:z \
    -v $HOME/simplex/xftp/logs:/var/opt/simplex-xftp:z \
    -v $HOME/simplex/xftp/files:/srv/xftp:z \
    simplexchat/xftp-server:latest

Installation script (Ubuntu)

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/simplex-chat/simplexmq/stable/install.sh -o simplex-server-install.sh &&\
if echo '53fcdb4ceab324316e2c4cda7e84dbbb344f32550a65975a7895425e5a1be757 simplex-server-install.sh' | sha256sum -c; then
  chmod +x ./simplex-server-install.sh
  ./simplex-server-install.sh
  rm ./simplex-server-install.sh
else
  echo "SHA-256 checksum is incorrect!"
  rm ./simplex-server-install.sh
fi

Build from source

Using Docker

Build from the stable branch:

git clone https://github.com/simplex-chat/simplexmq
cd simplexmq
git checkout stable
DOCKER_BUILDKIT=1 docker build -t local/smp-server --build-arg APP="smp-server" --build-arg APP_PORT="5223" .
DOCKER_BUILDKIT=1 docker build -t local/xftp-server --build-arg APP="xftp-server" --build-arg APP_PORT="443" .

Then run with the same Docker commands as above, replacing simplexchat/smp-server:latest with local/smp-server (and similarly for XFTP).

Native build

Install dependencies:

# Ubuntu
sudo apt-get update && apt-get install -y build-essential curl libffi-dev libffi7 libgmp3-dev libgmp10 libncurses-dev libncurses5 libtinfo5 pkg-config zlib1g-dev libnuma-dev libssl-dev
export BOOTSTRAP_HASKELL_GHC_VERSION=9.6.3
export BOOTSTRAP_HASKELL_CABAL_VERSION=3.10.3.0
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | BOOTSTRAP_HASKELL_NONINTERACTIVE=1 sh
ghcup set ghc "${BOOTSTRAP_HASKELL_GHC_VERSION}"
ghcup set cabal "${BOOTSTRAP_HASKELL_CABAL_VERSION}"
source ~/.ghcup/env

Build:

git clone https://github.com/simplex-chat/simplexmq
cd simplexmq
git checkout stable
cabal update
cabal build exe:smp-server exe:xftp-server

Find binaries:

cabal list-bin exe:smp-server
cabal list-bin exe:xftp-server

Initialize and run:

smp-server init [-l] -n <fqdn>   # or --ip <ip>
smp-server start

Linode StackScript

Deploy via Linode StackScript. Shared CPU Nanode with 1GB is sufficient.

Configuration options:

SMP Server store log flag for queue persistence (recommended)
Linode API token for automatic DNS and tagging (scopes: read/write for "linodes" and "domains")
Domain name (e.g., smp1.example.com) - the domain must exist in your Linode account

After deployment (up to 5 minutes), get the server address from Linode tags or SSH: smp://<fingerprint>@<fqdn>.

DigitalOcean 1-click

SimpleX Server 1-click app from DigitalOcean marketplace.

After deployment, get the fingerprint from the Droplet console (/etc/opt/simplex/fingerprint). Server address: smp://<fingerprint>@<ip_address>.

To use FQDN instead of IP:

smp-server delete
smp-server init [-l] -n <fqdn>

Monitoring

SMP and XFTP routers expose Prometheus metrics via a control port. The control port also supports commands for runtime inspection (queue counts, client counts, statistics). See module specs linked from each router section in spec/routers.md (Control, Prometheus, Stats).

Protocol references

SimpleX Messaging Protocol - SMP wire format and security properties
XFTP Protocol - data packet protocol
Push Notifications Protocol - NTF protocol
SimpleX Network overview - architecture and trust model

8.0 KiB Raw Permalink Blame History