{"id":20057704,"url":"https://github.com/raiden-network/raiden-service-bundle","last_synced_at":"2025-08-26T14:28:24.530Z","repository":{"id":36275068,"uuid":"143260441","full_name":"raiden-network/raiden-service-bundle","owner":"raiden-network","description":"Configuration and instructions for running the Raiden Service Bundle","archived":false,"fork":false,"pushed_at":"2023-05-25T16:53:00.000Z","size":521,"stargazers_count":7,"open_issues_count":24,"forks_count":15,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-05T07:12:14.522Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raiden-network.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}},"created_at":"2018-08-02T07:44:13.000Z","updated_at":"2023-11-21T00:33:25.000Z","dependencies_parsed_at":"2022-08-08T14:01:02.702Z","dependency_job_id":null,"html_url":"https://github.com/raiden-network/raiden-service-bundle","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raiden-network%2Fraiden-service-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raiden-network%2Fraiden-service-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raiden-network%2Fraiden-service-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raiden-network%2Fraiden-service-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raiden-network","download_url":"https://codeload.github.com/raiden-network/raiden-service-bundle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252514932,"owners_count":21760470,"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":[],"created_at":"2024-11-13T12:59:59.237Z","updated_at":"2025-05-05T14:31:19.286Z","avatar_url":"https://github.com/raiden-network.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Raiden Service Bundle (RSB)\n\n## What is this repository\n\nThis repository contains the documentation and configuration necessary to run a\nRaiden Service Bundle.\n\n**Current release:** [Latest](https://github.com/raiden-network/raiden-service-bundle/releases/latest)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Requirements](#requirements)\n  - [Hardware](#hardware)\n  - [Software](#software)\n- [Installation](#installation)\n- [Upgrades](#upgrades)\n- [Known issues](#known-issues)\n- [Contact / Troubleshooting](#contact-troubleshooting)\n- [Changelog](#changelog)\n\n## Overview\n\nThe Raiden Network uses a federation of [Matrix](https://matrix.org) servers as\nits transport layer and a set of services for improved usability. This set of\nservices is called the Raiden Service Bundle. To ensure reliability,\navailability and neutrality it is desirable that those services are being\noperated by multiple independent entities.\n\nTherefore we provide this repository which allows easy setup of such a service\nbundle. It uses docker and docker-compose for easy installation and upgrades.\n\nCurrently only this single-server configuration is supported; in the future we\nmay also provide configurations with services split among multiple servers.\n\n### Used software\n\n- docker\n- docker-compose\n- Synapse\n- Postgres\n- Traefik\n- Raiden Services (Pathfinding, Monitoring)\n\n### Structure\n\n\n```\n+-------------------+\n|                   |\n|   Raiden clients  |\n|                   |\n+---------+---------+\n          |https://\n==========|==========\n          |\n+---------v---------+                       Federation to\n|                 +-+--------------------\u003e  other Raiden\n|      Traefik    | |                       Matrix servers\n|                 |-+---------+----------------------+\n+---------+-------+-+         |                      |\n          |       |           |                      |\n+---------v-------v-+   +-----v----------------+ +---v-----------------+\n|                   |   |                      | |                     |\n|      Synapse      |   |  Raiden Pathfinding  | |  Raiden Monitoring  |\n|                   |   |                      | |                     |\n+---------+---------+   +-------------------+--+ +-+-------------------+\n          |                                 |      |\n+---------v---------+                     +-v- - - v -+\n|                   |                     |\n|     Postgres      |                        ETH_RPC  |\n|                   |                     |\n+-------------------+                     + - - - - - +\n```\n\n\nWe use Traefik as a reverse proxy and also utilize its capability of\nautomatically provisioning Let's Encrypt TLS certificates.\n\nThe Synapse server is being run in the so-called split worker configuration\nwhich increases throughput.\n\nThe database stores the message data. Since the transport layer is considered\nephemeral in Raiden it is not necessary to arrange for backups of the database\ndata.\n\n### Network\n\nAfter a successful deployment the following ports will be in use:\n\n- 80 - HTTP\n  - Redirects to HTTPS\n  - Let's Encrypt HTTP challenge for certificate provisioning\n- 443 - HTTPS\n  - Synapse (on subdomain `transport.$\u003cSERVER_NAME\u003e`)\n    - Client API access\n    - Server-to-Server federation\n  - Raiden Pathfinding Server (on subdomain `pfs.$\u003cSERVER_NAME\u003e`)\n  - Metrics export (IP restricted, see below)\n\n## Requirements\n\n### Hardware\n\nMinimum recommended for a production setup:\n\n- 16 GiB RAM\n-  8 Cores\n- 50 GiB SSD\n\nNote: The default Postgres configuration assumes 16GiB of system RAM\n\n### Software\n\n- Docker \u003e= 17.12\n- docker-compose \u003e= 1.21.0\n\n### Other\n\n- A domain (or subdomain) for exclusive use by this server\n- To ensure acceptable performance the server should be reserved for exclusive use by the RSB.\n\n## Installation\n\n\u003e **Note**\n\u003e\n\u003e Running an RSB provides important infrastructure to users of the Raiden\n\u003e Network and failures potentially affect a lot of users. It is therefore\n\u003e recommended to have devops experience and basic knowledge of the Ethereum\n\u003e ecosystem in order to run an RSB. Also a minimum commitment of a reasonable\n\u003e response time in case of outages is required.\n\n### Preparation\n\n1. Provision a server that meets the [hardware](#hardware) and [software](#software) requirements listed above.\n1. Ensure a domain (or subdomain) is available\n\n   Examples:\n   - raiden.somedomain.com\n   - raiden-service-bundle-somecompany.tld\n\n1. Configure `A` (and optionally `AAAA`) DNS records for the domain pointing to the servers IP address(es)\n1. Configure a `CNAME` DNS record for `*.\u003cdomain\u003e` pointing back to `\u003cdomain\u003e`\n\n\n**NOTE:**\n\nIf you intend to use a subdomain it is important to be aware of the security implications.\nSubdomains share Cookies and Browser LocalStorage with the apex domain.\nTherefore we strongly suggest that a subdomain is only used below an apex domain that does *not*\nhost an application that relies on either Cookies or LocalStorage for security relevant purposes (e.g. user authentication).\n\n\n### Installing the RSB\n\n**NOTE:**\nThis document will sometimes display release candidate versions, also known as pre-releases in the section below. You\ncan identify this, if there is an `rcX` at the end of the version (E.g. `2019.03.0rc5`). When in doubt, always check against the\n[latest full release](https://github.com/raiden-network/raiden-service-bundle/releases/latest). If the version is\ndifferent from what you see below, you should stick to the \"full release\" and replace the version accordingly.\n\n1. Clone the [current release version of this repository](https://github.com/raiden-network/raiden-service-bundle/tree/2022.05.0)\n   to a suitable location on the server:\n\n   ```shell\n   git clone -b 2022.05.0 https://github.com/raiden-network/raiden-service-bundle.git\n   ```\n1. Copy `.env.template` to `.env` and modify the values to fit your setup. Please read [Configuring the `.env` file](#configuring-the-env-file) for detailed information.\n   - We would appreciate it if you allow us access to the monitoring interfaces\n     (to do that uncomment the default values of the `CIDR_ALLOW_METRICS` and `CIDR_ALLOW_PROXY` settings).\n   - We also recommend that you provide your own monitoring. The setup of which is currently out of scope of this document.\n   - Please read the disclaimers for the path finding and monitoring services carefully and uncomment the variables `\u003cSERVICE\u003e_ACCEPT_DISCLAIMER` if you agree. Note, that without agreement the services won't start.\n1. If you haven't done so before, run `./register-service-provider.sh register` (it uses configuration values from `.env`). Please read the information provided [Registering as a RSB Provider](#registering-as-a-rsb-provider) carefully before executing the script.\n1. Run `docker-compose up -d` to start all services\n   - The services are configured to automatically restart in case of a crash or reboot\n\n**NOTE:**\n\nAfter a new RSB has been registered and added to the\n`known_servers/known_servers-production-v3.0.0.json` file it can take up to 24\nhours for the information to propagate to existing RSB installations.\n\nDuring this time some services will not yet be able to start successfully and\nlog various error messages. This is expected behaviour and will resolve itself.\n\nAfter the 24h have elapsed all services should run successfully.\nSee [verifying that the RSB is working](#verifying-that-the-rsb-is-working) below.\n\n### Configuring the `.env` file\nAfter cloning the repository the `.env` file needs to be configured. A template named `.env.template` is provided. Below you find a detailed list of the parameters to be set and their explanations.\n\n- `SERVER_NAME`: The host domain without protocol prefix `https://` respectively\n- `LETSENCRYPT_EMAIL`: Email address to use when requesting LetsEncrypt certificates\n- `CIDR_ALLOW_METRICS`: Metrics whitelist. IP address/network whitelists for access to non-public parts of the service. Uses CIDR notation. Separate multiple entries with commas. Example values: 10.0.0.0/16,10.1.2.3/32 or 10.1.2.3/32.\n- `CIDR_ALLOW_PROXY`: Proxy metrics / management interface whitelist\n- `WORKER_COUNT`: Number of worker processes to start, setting this to the number of CPUs is a good starting point\n- `DATA_DIR`: Data dir location. Optional, defaults to ./data in the checkout directory\n- `URL_KNOWN_FEDERATION_SERVERS`: URL to use to fetch federation whitelist - used only for testing\n- `KEYSTORE_FILE`: The keystore file which has to be located in ${DATA_DIR}/keystore\n- `PASSWORD`: Password to decrypt the keystore file\n- `ETH_RPC`: Ethereum RPC URL. This is used to communicate with the Ethereum blockchain. You can either [host a node yourself](https://ethereum.org/en/developers/docs/nodes-and-clients/run-a-node/) or use a service like [Infura](https://infura.io/). Regardless, the RSB requires a minimum of 200,000 requests per day and potentially more depending on traffic. Please make sure that the chosen service is able to handle this.\n- `PFS_ACCEPT_DISCLAIMER`: TRUE or FALSE if you accept the Pathfinding Service disclaimer or not. Read the Disclaimer [here](https://github.com/raiden-network/raiden-services/blob/f4bcb9c289e093754204fe18684e4b57558ea29b/src/pathfinding_service/constants.py#L34)\n- `MS_ACCEPT_DISCLAIMER`: TRUE or FALSE if you accept the Monitoring Service disclaimer or not. Read the Disclaimer [here](https://github.com/raiden-network/raiden-services/blob/f4bcb9c289e093754204fe18684e4b57558ea29b/src/monitoring_service/constants.py#L22)\n- `CHAIN_ID`: Chain ID of the connected Ethereum node.\n- `PFS_SERVICE_FEE`: The Pathfinding Service Fee to be paid for requests\n- `PFS_OPERATOR`: Official Operator Name\n- `PFS_INFO_MESSAGE`: Info message. Will be displayed on info endpoint.\n- `LOG_LEVEL`: 'INFO' or 'DEBUG' recommended\n- `SERVICE_REGISTRY`: The address of the ServiceRegistry contract to use. When running on mainnet, use the address of latest deployed contract which can be found here: https://github.com/raiden-network/raiden-contracts/blob/master/raiden_contracts/data_0.50.0/deployment_services_arbitrum-one.json#L6\n\n### Registering as a RSB Provider\nFor your newly deployed Raiden Service Bundle to be used by Raiden nodes it must be registered.\n\n1. **Registering in the Services Registry On-Chain**\n  - In order to register as a service provider you need to run the script [`register-service-provider.sh`](https://github.com/raiden-network/raiden-service-bundle/blob/master/register-service-provider.sh)` register`.\n  - In case you abort the script before finishing the registration process it is possible to continue the process by running the script again.\n  - Make sure that you have configured a keystore file (`$KEYSTORE_FILE` in `.env`). If not, the script will exit with an error and you cannot register as a service provider.\n  - Make sure you have ETH on the above account. An estimate will be shown during the registration process, before any transactions are sent.\n  - Make sure that the configured account has enough RDN funding to register as a service provider.\n    You can check the [registry contract](https://etherscan.io/address/0x1F54A809480E5E6349F09aaCaD14ec94C92EecD9#readContract) for the current price of a slot.\n    You will find the price under `3. currentPrice`. To get the price in RDN divide the value by (10^18).\n    The script will inform you about the price during the registration process as well.\n  - If you do not have sufficient RDN, you can either use an exchange of your choice or an on-chain decentralized exchange like [Uniswap](https://app.uniswap.org/#/swap?outputCurrency=0x255aa6df07540cb5d3d297f0d0d4d84cb52bc8e6) to acquire it.\n\n\n2. **Extending `known_servers/known_servers-production-v3.0.0.json`**\n  - In order to be whitelisted in the Matrix Federation, the list needs to be extended with your server name.\n  - [Create an issue](https://github.com/raiden-network/raiden-service-bundle/issues/new) and submit the\n   domain / URL of the newly deployed server for inclusion in the list of known servers.\n   Please, state your server name as you have set `$SERVER_NAME` in your `.env` file.\n  - It may take up to 24 hours for the federation to accept the server as a new member. Please note, that until this moment, the pathfinding service and monitoring service cannot run properly as they need to use the broadcasting rooms. Once the new server is accepted as part of the federation, all services will restart automatically.\n\n\n#### Interacting with the service registry contract\nBesides the subcommand `register` which can be used to register as a RSB provider, there are several other subcommands to interact with the service registry contract.\n\nCommands:\n\n- *extend*    Extend the duration of a service registration\n- *info*      Show information about current registration and deposits\n- *register*  Registers the address of a service deployment with the `ServiceRegistry`.\n- *withdraw*  Withdraw tokens deposited to the ServiceRegistry.\n\nYou can call [`register-service-provider.sh`](https://github.com/raiden-network/raiden-service-bundle/blob/master/register-service-provider.sh)` \u003ccommand\u003e` to use them.\n\n### Verifying that the RSB is working\n\nCheck the status of the services by executing `docker-compose ps`.\nIf any services are in a state other than `Up`, `Up (healthy)` or `Exit 0` after the elapse of the 24h waiting period a configuration problem is the most likely cause.\nSee [troubleshooting the RSB installation](#troubleshooting-the-rsb-installation) below in that case.\n\n- Matrix\n  - Check that the following endpoints return a successful response (HTTP status 200):\n    - `https://transport.\u003cSERVER_NAME\u003e/_matrix/client/versions`\n\n- PFS\n  - Check that the `latest_committed_block` is increasing regularly:\n\n    `docker-compose logs --tail 100 pfs | grep latest_committed_block`\n  - Check that the following endpoint returns a successful response (HTTP status 200):\n    - `https://pfs.\u003cSERVER_NAME\u003e/api/v1/info`\n\n- MS\n  - Check that the `latest_confirmed_block` is increasing regularly:\n\n    `docker-compose logs --tail 100 ms | grep latest_confirmed_block`\n\n\n### Troubleshooting the RSB installation\n\nIf you experience any unexpected behavior while installing the RSB, please do not hesitate to contact the development team. The fastest way to reach out to us is via the public [Raiden Gitter channel](https://gitter.im/raiden-network/raiden).\nOtherwise, you can also open an issue in this repository with the predefined template for a [bug report](https://github.com/raiden-network/raiden-service-bundle/issues/new?template=bug_report.md)\n\n\n## Upgrades\n\nTo upgrade to a new release please refer to the [`upgrading document`](./UPGRADING.md) for any\nnecessary configuration changes.\n\nAfterwards run the following commands:\n\n```shell\ngit fetch origin --tags\ngit reset --hard \u003cnew-release-tag\u003e\ndocker-compose pull\ndocker-compose up -d --remove-orphans\n```\n## Notes:\n\n - A 'purger' service will run once a day, removing inactive users from global rooms\n  to save disk space and processing performance.\n - If necessary it will restart the ``synapse`` service to fetch an up-to-date\n  whitelist of servers.\n\n## Known issues\n\n### Protection against Spam / (D)DoS attacks\n\nThere is currently only some protection against Spam and / or DDoS attacks.\nThis will be addressed in future updates.\n\n### Known servers\n\nThe known servers the Raiden clients try to connect to are currently tracked in\nthe *.yml files in this repository. These lists are used by Raiden clients when\nthe ``--matrix-server=auto`` (default) option is used, for automatically\nselecting a transport server, based on response times. We intend to change this\nin the future to use a decentralized scheme (for example an on-chain registry).\n\n\n## Contact / Troubleshooting \u003ca name=\"contact-troubleshooting\" /\u003e\n\nTo report issues or request help with the setup please [open an issue](https://github.com/raiden-network/raiden-service-bundle/issues/new)\nor contact us via email at contact@raiden.nework.\n\n\n## Changelog\nSee [`CHANGELOG.md`](./CHANGELOG.md).\n\n\n## Licenses\n\nThe code and documentation in this repository are released under the [MIT license](./LICENSE).\n\nThis repository contains instructions to install third party software. Those are licensed as follows:\n\n- [Traefik](https://github.com/containous/traefik): [MIT](https://github.com/containous/traefik/blob/6a55772cda1684546a6a5456b6847e0f9b3df44d/LICENSE.md)\n- [Synapse](https://github.com/matrix-org/synapse): [Apache 2.0](https://github.com/matrix-org/synapse/blob/047ac0cbba25ccffb93d92b46254a58f48ddaf9c/LICENSE)\n- [PostgreSQL](https://www.postgresql.org): [PostgreSQL License](https://www.postgresql.org/about/licence/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraiden-network%2Fraiden-service-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraiden-network%2Fraiden-service-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraiden-network%2Fraiden-service-bundle/lists"}