crossdesk/docs/SELF_HOSTING_EN.md

Self-hosting

Back to README · 中文

Signaling and TURN deployment are maintained in CrossDesk Server. Use matching server configuration files from the same release. This guide focuses on deployment entry points and the current client UI.

1. Deploy the server

These steps target a Linux server with Docker Engine and the Compose plugin installed. Confirm that docker compose version works. The current Compose deployment uses host networking and runs signaling and Coturn separately.

Follow the server deployment guide. Download compose.yaml and env.example from its Releases into one directory and run there:

cp env.example .env

Edit .env in a text editor and complete these values before starting the services. The repository also provides an environment example.

Variable	Value
CROSSDESK_IMAGE	A fixed release tag matching the configuration
EXTERNAL_IP / INTERNAL_IP	Your actual public / private server IPs
CROSSDESK_SERVER_PORT	Signaling port, e.g. 9099
COTURN_PORT	Relay port, e.g. 3478
MIN_PORT / MAX_PORT	TURN media port range
COTURN_AUTH_SECRET	Secret shared by signaling and Coturn; never enter it in clients
COTURN_STATELESS_NONCE_SECRET	A separately generated, persistent nonce secret
CROSSDESK_DATA_DIR / CROSSDESK_LOG_DIR	Persistent data, certificate, and log locations

Generate each secret separately with openssl rand -hex 32. Allow signaling TCP, relay TCP/UDP, and the selected media UDP range through the firewall and cloud security group. Mounts and networking are defined in the official Compose file.

After saving the configuration, validate it and start the services:

sudo docker compose config -q
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

2. Configure desktop clients

For a self-signed deployment, complete the certificate trust steps on both clients before checking their connection status.

1. Disconnect existing sessions and open ☰ → Settings.
2. Scroll down and click Self-Hosted Config.
3. Enter Server Address, Signal Service Port, and Relay Service Port, then confirm. Enter only the hostname or IP in the address field, without a URL scheme, path, or port.
4. Enable the checkbox beside Self-Hosted Config, then click OK in the parent settings window.
5. Configure both the controller and host this way. Once both report a server connection, connect using the host's currently displayed ID.

Recheck the device ID after changing servers. Device identities belong to their server; do not assume an old ID carries over.

3. Trust the TLS certificate

The signaling certificate must cover the configured hostname/IP and be trusted by the client OS. For a public CA certificate, configure the server's certificate chain as instructed by the server project. For a self-signed deployment, trust the root certificate belonging to your own server.

The default certificate generator includes only EXTERNAL_IP in the certificate's subject alternative name. Use that IP in the client, or supply a certificate covering your custom domain. The startup script reuses existing certificates; editing the IP in .env does not update them automatically.

Default certificates are stored in the data directory's certs/ folder. Copy your server's api.crossdesk.cn_root.crt to the client and run the relevant command. Do not trust a root certificate from an unknown source.

Windows — administrator PowerShell:

certutil -addstore "Root" "C:\path\to\api.crossdesk.cn_root.crt"

Ubuntu / Debian:

sudo cp /path/to/api.crossdesk.cn_root.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

macOS:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain /path/to/api.crossdesk.cn_root.crt

Reopen the client afterwards. Self-signed certificates still support encryption; correct root trust and hostname verification are required.

4. Web and iOS

• Web: configure your signaling endpoint following the Web Client project. The browser must trust its certificate; do not disable TLS verification to work around certificate errors.
• iOS: enter the signaling host, signaling port, and STUN/TURN port under Settings → Server, then apply. A self-signed deployment requires installing and trusting its root certificate on the device.

Troubleshooting order

• Server disconnected / TLS error: check the host, signaling port, certificate dates, certificate hostname, and root trust.
• Server connected, device offline: confirm both clients use the same server, keep the host running, and copy its current ID again.
• P2P failed: check the relay setting, Coturn status, relay/media ports, and compatibility between client and server versions.
• Environment changes ignored: run sudo docker compose up -d from the configuration directory. Restarting existing containers alone does not apply changed environment variables.

See the server maintenance documentation for logs, backups, and migration.