{"id":13470578,"url":"https://github.com/strukturag/nextcloud-spreed-signaling","last_synced_at":"2025-05-14T15:05:51.058Z","repository":{"id":36966341,"uuid":"263268773","full_name":"strukturag/nextcloud-spreed-signaling","owner":"strukturag","description":"Standalone signaling server for Nextcloud Talk.","archived":false,"fork":false,"pushed_at":"2025-05-05T06:56:48.000Z","size":3773,"stargazers_count":427,"open_issues_count":29,"forks_count":76,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-05T07:40:24.463Z","etag":null,"topics":["call","clustering","etcd","go","golang","grpc","nextcloud","open-source","screensharing","spreed","talk","video","webrtc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strukturag.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-12T07:47:23.000Z","updated_at":"2025-05-05T06:56:44.000Z","dependencies_parsed_at":"2023-11-29T08:25:04.490Z","dependency_job_id":"9976795a-33b1-4111-8dd0-a023ebdf7efc","html_url":"https://github.com/strukturag/nextcloud-spreed-signaling","commit_stats":{"total_commits":1009,"total_committers":22,"mean_commits":45.86363636363637,"dds":0.33201189296333,"last_synced_commit":"d692a3b83c72d0631b686868edaac053940e89cb"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukturag%2Fnextcloud-spreed-signaling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukturag%2Fnextcloud-spreed-signaling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukturag%2Fnextcloud-spreed-signaling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukturag%2Fnextcloud-spreed-signaling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strukturag","download_url":"https://codeload.github.com/strukturag/nextcloud-spreed-signaling/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254168986,"owners_count":22026207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["call","clustering","etcd","go","golang","grpc","nextcloud","open-source","screensharing","spreed","talk","video","webrtc"],"created_at":"2024-07-31T16:00:32.188Z","updated_at":"2025-05-14T15:05:51.051Z","avatar_url":"https://github.com/strukturag.png","language":"Go","funding_links":[],"categories":["Go","golang","Other APIs"],"sub_categories":[],"readme":"# Spreed standalone signaling server\n\n![Build Status](https://github.com/strukturag/nextcloud-spreed-signaling/actions/workflows/test.yml/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/strukturag/nextcloud-spreed-signaling/badge.svg?branch=master)](https://coveralls.io/github/strukturag/nextcloud-spreed-signaling?branch=master)\n[![Documentation Status](https://readthedocs.org/projects/nextcloud-spreed-signaling/badge/?version=latest)](https://nextcloud-spreed-signaling.readthedocs.io/en/latest/?badge=latest)\n[![Go Report](https://goreportcard.com/badge/github.com/strukturag/nextcloud-spreed-signaling)](https://goreportcard.com/report/github.com/strukturag/nextcloud-spreed-signaling)\n\nThis repository contains the standalone signaling server which can be used for\nNextcloud Talk (https://apps.nextcloud.com/apps/spreed).\n\nSee https://nextcloud-spreed-signaling.readthedocs.io/en/latest/ for further\ninformation on the API of the signaling server.\n\n\n## Building\n\nThe following tools are required for building the signaling server.\n\n- git\n- go \u003e= 1.23\n- make\n\nUsually the last two versions of Go are supported. This follows the release\npolicy of Go: https://go.dev/doc/devel/release#policy\n\nThese additional tools are required to generate code from `.proto` files.\n\n- protobuf-compiler \u003e= 3\n\nAll other dependencies are fetched automatically while building.\n\n    $ make build\n\nor on FreeBSD\n\n    $ gmake build\n\nAfterwards the binary is created as `bin/signaling`.\n\n\n## Configuration\n\nA default configuration file is included as `server.conf.in`. Copy this to\n`server.conf` and adjust as necessary for the local setup. See the file for\ncomments about the different parameters that can be changed.\n\n\n## Running\n\nThe signaling server connects to a NATS server (https://nats.io/) to distribute\nmessages between different instances. See the NATS documentation on how to set\nup a server and run it.\n\nOnce the NATS server is running (and the URL to it is configured for the\nsignaling server), you can start the signaling server.\n\n    $ ./bin/signaling\n\nBy default, the configuration is loaded from `server.conf` in the current\ndirectory, but a different path can be passed through the `--config` option.\n\n    $ ./bin/signaling --config /etc/signaling/server.conf\n\n### Running as daemon\n\n#### systemd\n\nCreate a dedicated group and user:\n\n```bash\nsudo groupadd --system signaling\nsudo useradd --system \\\n    --gid signaling \\\n    --shell /usr/sbin/nologin \\\n    --comment \"Standalone signaling server for Nextcloud Talk.\" \\\n    signaling\n```\n\nCopy `server.conf.in` to `/etc/signaling/server.conf` and fix permissions:\n\n```bash\nsudo chmod 600 /etc/signaling/server.conf\nsudo chown signaling: /etc/signaling/server.conf\n```\n\nCopy `dist/init/systemd/signaling.service` to `/etc/systemd/system/signaling.service` (adjust abs. path in `ExecStart` to match your binary location!)\n\nEnable and start service:\n\n```bash\nsystemctl enable signaling.service\nsystemctl start signaling.service\n```\n\n### Running with Docker\n\nOfficial docker containers for the signaling server and -proxy are available on\nDocker Hub at https://hub.docker.com/r/strukturag/nextcloud-spreed-signaling\n\nSee the `README.md` in the `docker` subfolder for details.\n\n\n#### Docker Compose\n\nYou will likely have to adjust the Janus command line options depending on the exact network configuration on your server. Refer to [Setup of Janus](#setup-of-janus) and the Janus documentation for how to configure your Janus server.\n\nCopy `server.conf.in` to `server.conf` and adjust it to your liking.\n\nIf you're using the [docker-compose.yml](docker/docker-compose.yml) configuration as is, the MCU Url must be set to `ws://localhost:8188`, the NATS Url must be set to `nats://localhost:4222`, and TURN Servers must be set to `turn:localhost:3478?transport=udp,turn:localhost:3478?transport=tcp`.\n\n```bash\ndocker-compose build\ndocker-compose up -d\n```\n\nPlease note that docker-compose v2 is required for building while most\ndistributions will ship older versions. You can download a recent version from\nhttps://docs.docker.com/compose/install/\n\n\n## Setup of NATS server\n\nThere is a detailed description on how to install and run the NATS server\navailable at https://docs.nats.io/running-a-nats-service/introduction\n\nYou can use the `gnatsd.conf` file as base for the configuration of the NATS\nserver.\n\n\n## Setup of Janus\n\nA Janus server (from https://github.com/meetecho/janus-gateway) can be used to\nact as a WebRTC gateway. See the documentation of Janus on how to configure and\nrun the server. At least the `VideoRoom` plugin and the websocket transport of\nJanus must be enabled.\n\nThe signaling server uses the `VideoRoom` plugin of Janus to manage sessions.\nAll gateway details are hidden from the clients, all messages are sent through\nthe signaling server. Only WebRTC media is exchanged directly between the\ngateway and the clients.\n\nEdit the `server.conf` and enter the URL to the websocket endpoint of Janus in\nthe section `[mcu]` and key `url`. During startup, the signaling server will\nconnect to Janus and log information of the gateway.\n\nThe maximum bandwidth per publishing stream can also be configured in the\nsection `[mcu]`, see properties `maxstreambitrate` and `maxscreenbitrate`.\n\n\n### Use multiple Janus servers\n\nTo scale the setup and add high availability, a signaling server can connect to\none or multiple proxy servers that each provide access to a single Janus server.\n\nFor that, set the `type` key in section `[mcu]` to `proxy` and set `url` to a\nspace-separated list of URLs where a proxy server is running.\n\nEach signaling server that connects to a proxy needs a unique token id and a\npublic / private RSA keypair. The token id must be configured as `token_id` in\nsection `[mcu]`, the path to the private key file as `token_key`.\n\n\n### Setup of proxy server\n\nThe proxy server is built with the standard make command `make build` as\n`bin/proxy` binary. Copy the `proxy.conf.in` as `proxy.conf` and edit section\n`[tokens]` to the list of allowed token ids and filenames of the public keys\nfor each token id. See the comments in `proxy.conf.in` for other configuration\noptions.\n\nWhen the proxy process receives a `SIGHUP` signal, the list of allowed token\nids / public keys is reloaded. A `SIGUSR1` signal can be used to shutdown a\nproxy process gracefully after all clients have been disconnected. No new\npublishers will be accepted in this case.\n\n\n### Remote streams (preview)\n\nWith Janus 1.1.0 or newer, remote streams are supported, i.e. a subscriber can\nreceive a published stream from any server. For this, you need to configure\n`hostname`, `token_id` and `token_key` in the proxy configuration. Each proxy\nserver also supports configuring maximum `incoming` and `outgoing` bandwidth\nsettings, which will also be used to select remote streams.\nSee `proxy.conf.in` in section `app` for details.\n\n\n## Clustering\n\nThe signaling server supports a clustering mode where multiple running servers\ncan be interconnected to form a single \"virtual\" server. This can be used to\nincrease the capacity of the signaling server or provide a failover setup.\n\nFor that a central NATS server / cluster must be used by all instances. Each\ninstance must run a GRPC server (enable `listening` in section `grpc` and\noptionally setup certificate, private key and CA). The list of other GRPC\ntargets must be configured as `targets` in section `grpc` or can be retrieved\nfrom an etcd cluster. See `server.conf.in` in section `grpc` for configuration\ndetails.\n\n\n## Setup of frontend webserver\n\nUsually the standalone signaling server is running behind a webserver that does\nthe SSL protocol or acts as a load balancer for multiple signaling servers.\n\nThe configuration examples below assume a pre-configured webserver (nginx or\nApache) with a working HTTPS setup, that is listening on the external interface\nof the server hosting the standalone signaling server.\n\nAfter everything has been set up, the configuration can be tested using `curl`:\n\n    $ curl -i https://myserver.domain.invalid/standalone-signaling/api/v1/welcome\n    HTTP/1.1 200 OK\n    Date: Thu, 05 Jul 2018 09:28:08 GMT\n    Server: nextcloud-spreed-signaling/1.0.0\n    Content-Type: application/json; charset=utf-8\n    Content-Length: 59\n\n    {\"nextcloud-spreed-signaling\":\"Welcome\",\"version\":\"1.0.0\"}\n\n\n### nginx\n\nNginx can be used as frontend for the standalone signaling server without any\nadditional requirements.\n\nThe backend should be configured separately so it can be changed in a single\nlocation and also to allow using multiple backends from a single frontend\nserver.\n\nAssuming the standalone signaling server is running on the local interface on\nport `8080` below, add the following block to the nginx server definition in\n`/etc/nginx/sites-enabled` (just before the `server` definition):\n\n    upstream signaling {\n        server 127.0.0.1:8080;\n    }\n\nTo proxy all requests for the standalone signaling to the correct backend, the\nfollowing `location` block must be added inside the `server` definition of\nthe same file:\n\n    location /standalone-signaling/ {\n        proxy_pass http://signaling/;\n        proxy_http_version 1.1;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    }\n\n    location /standalone-signaling/spreed {\n        proxy_pass http://signaling/spreed;\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"Upgrade\";\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    }\n\n\nExample (e.g. `/etc/nginx/sites-enabled/default`):\n\n    upstream signaling {\n        server 127.0.0.1:8080;\n    }\n\n    server {\n        listen 443 ssl http2;\n        server_name myserver.domain.invalid;\n\n        # ... other existing configuration ...\n\n        location /standalone-signaling/ {\n            proxy_pass http://signaling/;\n            proxy_http_version 1.1;\n            proxy_set_header Host $host;\n            proxy_set_header X-Real-IP $remote_addr;\n            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        }\n\n        location /standalone-signaling/spreed {\n            proxy_pass http://signaling/spreed;\n            proxy_http_version 1.1;\n            proxy_set_header Upgrade $http_upgrade;\n            proxy_set_header Connection \"Upgrade\";\n            proxy_set_header Host $host;\n            proxy_set_header X-Real-IP $remote_addr;\n            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        }\n    }\n\n\n### Apache\n\nTo configure the Apache webservice as frontend for the standalone signaling\nserver, the modules `mod_proxy_http` and `mod_proxy_wstunnel` must be enabled\nso WebSocket and API backend requests can be proxied:\n\n    $ sudo a2enmod proxy\n    $ sudo a2enmod proxy_http\n    $ sudo a2enmod proxy_wstunnel\n\nNow the Apache `VirtualHost` configuration can be extended to forward requests\nto the standalone signaling server (assuming the server is running on the local\ninterface on port `8080` below):\n\n    \u003cVirtualHost *:443\u003e\n\n        # ... existing configuration ...\n\n        # Enable proxying Websocket requests to the standalone signaling server.\n        ProxyPass \"/standalone-signaling/\"  \"ws://127.0.0.1:8080/\"\n\n        RequestHeader set X-Real-IP %{REMOTE_ADDR}s\n\n        RewriteEngine On\n        # Websocket connections from the clients.\n        RewriteRule ^/standalone-signaling/spreed/$ - [L]\n        # Backend connections from Nextcloud.\n        RewriteRule ^/standalone-signaling/api/(.*) http://127.0.0.1:8080/api/$1 [L,P]\n\n        # ... existing configuration ...\n\n    \u003c/VirtualHost\u003e\n\n### Caddy\n\n#### v1\n\n[Caddy (v1)](https://caddyserver.com/v1/) configuration:\n\n```\nmyserver.domain.invalid {\n  proxy /standalone-signaling/ http://127.0.0.1:8080 {\n    without /standalone-signaling\n    transparent\n    websocket\n  }\n}\n```\n\n#### v2\n\n[Caddy (v2)](https://caddyserver.com/) configuration:\n\n```\nmyserver.domain.invalid {\n  route /standalone-signaling/* {\n    uri strip_prefix /standalone-signaling\n    reverse_proxy http://127.0.0.1:8080\n    header_up X-Real-IP {remote_host}\n  }\n}\n```\n\n## Setup of Nextcloud Talk\n\nLogin to your Nextcloud as admin and open the additional settings page. Scroll\ndown to the \"Talk\" section and enter the base URL of your standalone signaling\nserver in the field \"External signaling server\".\nPlease note that you have to use `https` if your Nextcloud is also running on\n`https`. Usually you should enter `https://myhostname/standalone-signaling` as\nURL.\n\nThe value \"Shared secret for external signaling server\" must be the same as the\nproperty `secret` in section `backend` of your `server.conf`.\n\nIf you are using a self-signed certificate for development, you need to uncheck\nthe box `Validate SSL certificate` so backend requests from Nextcloud to the\nsignaling server can be performed.\n\n\n## Benchmarking the server\n\nA simple client exists to benchmark the server. Please note that the features\nthat are benchmarked might not cover the whole functionality, check the\nimplementation in `src/client` for details on the client.\n\nTo authenticate new client connections to the signaling server, the client\nstarts a dummy authentication handler on a local interface and passes the URL\nin the `hello` request. Therefore the signaling server should be configured to\nallow all backend hosts (option `allowall` in section `backend`).\n\nThe client is not compiled by default, but can be using the `client` target:\n\n    $ make client\n\nUsage:\n\n    $ ./bin/client\n    Usage of ./bin/client:\n      -addr string\n            http service address (default \"localhost:28080\")\n      -config string\n            config file to use (default \"server.conf\")\n      -maxClients int\n            number of client connections (default 100)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrukturag%2Fnextcloud-spreed-signaling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrukturag%2Fnextcloud-spreed-signaling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrukturag%2Fnextcloud-spreed-signaling/lists"}