{"id":2137709,"url":"https://github.com/radicle-dev/radicle-client-services","last_synced_at":"2025-07-13T12:31:36.748Z","repository":{"id":37204811,"uuid":"374698959","full_name":"radicle-dev/radicle-client-services","owner":"radicle-dev","description":"Services backing the Radicle client interfaces.","archived":true,"fork":false,"pushed_at":"2022-11-25T22:30:00.000Z","size":907,"stargazers_count":32,"open_issues_count":11,"forks_count":10,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-05T11:09:24.472Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radicle-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2021-06-07T14:39:03.000Z","updated_at":"2025-02-07T17:34:09.000Z","dependencies_parsed_at":"2022-07-14T08:17:15.489Z","dependency_job_id":null,"html_url":"https://github.com/radicle-dev/radicle-client-services","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/radicle-dev/radicle-client-services","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radicle-dev%2Fradicle-client-services","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radicle-dev%2Fradicle-client-services/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radicle-dev%2Fradicle-client-services/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radicle-dev%2Fradicle-client-services/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radicle-dev","download_url":"https://codeload.github.com/radicle-dev/radicle-client-services/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radicle-dev%2Fradicle-client-services/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265139262,"owners_count":23717280,"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-01-22T00:41:20.094Z","updated_at":"2025-07-13T12:31:36.361Z","avatar_url":"https://github.com/radicle-dev.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Radicle Client Services\n\n🏕️ Services backing the Radicle client interfaces.\n\n## Setting up a *Seed Node*\n\nA *seed node* is a type of node that replicates and distributes Radicle\nprojects making them freely and publicly accessible on the web, and via\npeer-to-peer protocols.\n\nThough it's possible to rely on shared infrastructure and community seed nodes,\nit is recommend for most teams and communities to self-host their projects in true\npeer-to-peer fashion. This can be achieved by running `radicle-http-api` and\n`radicle-git-server` on a server or instance in the cloud.\n\n### `radicle-http-api`\n\nThe Radicle HTTP API is a lightweight HTTP service that runs on top of a Radicle\n*monorepo*. As a reminder, the \"monorepo\" is the repository that contains all\nprojects and associated metadata stored and replicated by Radicle Link.\n\nBy running the API, projects stored in the local monorepo are exposed via a\nJSON HTTP API. This can enable clients to query project source code directly\nvia HTTP, without having to run a node themselves. In particular, the Radicle\nweb client was built around this API.\n\n### `radicle-git-server`\n\nThe Radicle Git Server is an HTTP server that can serve repositories managed\nby Radicle. Since Radicle projects are stored in a shared, monolithic repository,\ncommands like `git clone` cannot work out of the box. The Radicle Git Server\nmaps requests to specific namespaces in the shared repository and allows a Radicle\nnode to act as a typical Git server. It is then possible to clone a project\nby simply specifying its ID, for example:\n\n    git clone https://seed.alt-clients.radicle.xyz/hnrkyghsrokxzxpy9pww69xr11dr9q7edbxfo.git\n\n### Service setup\n\nThe services should have access to the same file-system. The git server requires\n*write* access to the file system, while the HTTP API only requires *read* access.\n\nFor this setup to work, it's import to point all services to the same *root*,\nwhich is the path to the monorepo, eg.:\n\n    $ radicle-http-api --root ~/.radicle/root …\n    $ radicle-git-server --root ~/.radicle/root …\n\nThis ensures the API and Git server can read the same state.\n\n#### Identity file\n\nNodes on the Radicle peer-to-peer network are identified with a *Peer ID*,\nwhich is essentially an encoding of a public key. This identity needs to\nbe specified on the CLI via the `--identity` flag, similar to SSH's `-i`\nflag. Specifically, the path to the private key file should be used. If\nno private key is found at that path, a new key will be generated.\n\n#### Firewall configuration\n\nFor `radicle-http-api`, an HTTP port of your choosing should be opened. This port\ncan then be specified via the `--listen` parameter, eg.\n`radicle-http-api --listen 0.0.0.0:8777`.  The default port is `8777`.\n\nFor `radicle-git-server`, it is recommended that port `443` be open.\n\n#### Using authorized-keys for Authorization\n\nBy default, the pre-receive hook will check the mono-repository for a authorized-keys\npublic key file on push. If it exists, it will check the public key's fingerprint\nmatches the $GIT_PUSH_CERT_KEY set by the http-backend.\nThe $GIT_PUSH_CERT_KEY is used to find the file in the namespace tree, \ncomparing the fingerprint in the authorized keyring against the signed certificate.\n\n#### TLS\n\nFor `radicle-http-api` and `radicle-git-server`, it's important to setup TLS\nwhen running in production.  This is to allow for compatibility with web\nclients that will mostly be using the `https` protocol. Web browser nowadays do\nnot allow requests to unencrypted HTTP servers from websites using TLS.\n\nThe API service has built-in support for TLS, so there is no need to set up\nHTTPS termination via a separate service. Simply pass in the `--tls-cert`\nand `--tls-key` flags to enable TLS.\n\nCertificates can be obtained from *Let's Encrypt*, using [Certbot](https://certbot.eff.org/).\n\n#### Logging\n\nTo enable logging for either service, set the `RUST_LOG` environment variable.\nSetting it to `info` is usually enough, but `debug` is also possible.\n\n### ENS setup\n\nOnce these services are running, users wishing to point Radicle clients to them\nfor project browsing should set the relevant records on ENS. This requires\nan ENS name to be registered for each seed node.\n\nTo point Radicle clients to the right seed endpoint, use the\n`eth.radicle.seed.host` text record, usually labeled \"Seed Host\" to the\nseed host, eg `seed.acme.org`.\n\nThese records can be set on the web client. For example, the records for the\nAlt.-clients org can be found at \u003chttps://app.radicle.network/registrations/alt-clients.radicle.eth\u003e.\n\n### Docker\n\nThere are `Dockerfile` provided for both services in the respective directories.\n\n#### Building\n\nTo build the containers, run:\n\n    $ docker build -t radicle-services/http-api -f http-api/Dockerfile .\n    $ docker build -t radicle-services/git-server -f git-server/Dockerfile .\n\n#### Running\n\nTo run the HTTP API, run:\n\n    $ docker run \\\n        --init \\\n        -e RUST_LOG=info \\\n        -p 8777:8777 \\\n        -v $HOME/.radicle:/app/radicle radicle-services/http-api \\\n        --tls-cert /app/radicle/fullchain.pem \\\n        --tls-key /app/radicle/privkey.pem\n\nMake sure your TLS certificate files can be found under `$HOME/.radicle`. If you\nare not using TLS termination, simply omit the `--tls-*` arguments.\n\nRunning `radicle-git-server` is more or less identical to running the HTTP API.\n\nYou may also want to detach the process (`-d`) and run with a TTY in interactive\nmode (`-it`).\n\n### Docker Compose\n\nAs an alternative to building the containers yourself, a `docker-compose.yml`\nfile is included in the repository. To run the services via Docker Compose, you\nhave to:\n\n1. Install Docker and Docker Compose\n2. Clone this repository\n3. Set the necessary environment variables\n4. Start the radicle client services via Docker Compose\n\nTo install Docker Compose, run:\n\n    sudo apt-get install docker\n    pip install docker-compose\n\nThen clone this repository and `cd` into it:\n\n    git clone \u003crepository-url\u003e radicle-client-services\n    cd radicle-client-service\n\nThen set `RADICLE_DOMAIN` to your seed node's domain, eg. `seed.cloudhead.io`.\nThese can be set in the environment, or in a `.env` file in the current\ndirectory.\n\nFinally, pull the containers and start the services:\n\n    docker-compose pull\n    docker-compose up --detach\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradicle-dev%2Fradicle-client-services","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradicle-dev%2Fradicle-client-services","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradicle-dev%2Fradicle-client-services/lists"}