Abstract

The documentation for my collection of tools for the Radicle peer-to-peer Git collaboration system.

About Radicle

Radicle is an open source peer-to-peer stack for collaborative usage of the Git version control system. It augments Git with functionalities typically found in Git hosting services, such as GitHub, but in a decentralized (i.e. peer-to-peer) fashion to break one’s dependence on centralized services. While Radicle supports centralized services (e.g. GitHub) as a hosting back-end, we will concentrate on its decentralized hosting support (via IPFS).

Radicle is command line centered, and provides a CLI tool called rad for users to work with Radicle projects. Each project is a Git repository plus additional data managed by Radicle (issues, projects…​). The Radicle project data is shared over IPFS in order to enable collaboration with peers.

Radicle’s facilities, fit into the three following dimensions:

Issues

Radicle supports storing project issues, and querying/manipulating them via the command line. This removes the need for an external issue tracker, such as the one provided by GitHub, and the issue history will be stored alongside the repository.

Patches

Similar to GitHub pull requests, Radicle supports patch proposals. Basically, you may (via the rad tool) propose a patch to a project based on a commit. A project maintainer may accept or reject a proposal. Unlike e.g. GitHub pull requests, Radicle patch proposals are stored together alongside your repository, so the history of these isn’t locked to a vendor.

Hosting

As already mentioned, Radicle supports sharing of your Git repository, either via a traditional hosting service (e.g. GitHub) or peer-to-peer (via IPFS). Sharing code over IPFS is more complicated than via a centralized service such as GitHub, but we think it’s worth it in order to avoid vendor lock-in.

Git Sharing/Hosting

Radicle supports creating a project with either a centralized remote repository for code sharing/hosting or with an IPFS remote.

If you choose an IPFS remote, the standard remote (i.e. origin) gets configured with an IPNS URI. When you synchronize with this, the git-remote-ipfs Git remote helper will be used to push and pull data. By default the remote helper will be configured to use Radicle’s IPFS daemon, via the ipfs.apiurl setting in .git/config in your project.

Radicle Backup [WIP]

Caution
This is a work in progress as the Radicle Backup tool is still under development.

Our first, and perhaps most basic, tool is Radicle Backup, which supports backing up Radicle projects. It will collect both the Git repository itself and the Radicle state (from IPFS) in an archive (brotli compressed tarball). In the future this archive should also be uploaded to a storage back-end (DigitalOcean Spaces).

The tool additionally supports restoring of backup archives.

Backing Up a Project

The command radicle-backup backup <project> will back up a Radicle project to a brotli compressed tarball. The backup will consist of the Git repository itself and Radicle project state in the form of state machines, for the project itself, issues, patches and repository. Each state machine is represented as a linked list of expression blocks (except for the repository one) added by Radicle to IPLD/IPFS. The repository state machine is simply JSON data, although also added to IPLD.

Note
Radicle uses its own IPFS network, so radicle-backup has to use Radicle’s dedicated IPFS server to get project state.

More specifically, for each change to a state machine (except for the repository one), Radicle adds a block of expressions to IPLD that points to the most recent block as its previous link (thus implementing a linked list) and updates the machine’s IPNS entry to point to this newly added block.

The project state machine refers to other state machines belonging to the project, i.e. issues, patches and repository. The backup tool determines the identity of those state machines from the project state machine.

When backing up a project, the tool gathers the content of each connected Radicle state machine from IPLD and saves this metadata in an embedded database, which gets stored in the backup archive.

Restoring a Project

The command radicle-backup restore <archive> <destination> will restore a Radicle project from a tarball produced by Radicle Backup. The project gets unpacked beneath the destination directory provided by the user, and afterwards the Radicle state machines (project/issues/patches/repository) get restored, with their content re-added to IPLD. IPNS entries of state machines also get re-published.

Note
Radicle uses its own IPFS network, so radicle-backup has to use Radicle’s own IPFS server to restore project state.

Radicle Project Pinning Service [WIP]

Caution
This is a work in progress as the Radicle Project pinning service is still under development.

The Radicle Project pinning service ensures availability of Radicle projects, through so-called IPFS pinning. Pinning in the context of IPFS means that an IPFS node will keep certain data, rather than just cache it when it’s in use, which is the default mode.

Because the normal behaviour of IPFS is to just cache data, when you share your Radicle projects via IPFS there’s no guarantee that they will remain available except for when you seed them yourself. This is where so-called pinning services come in; they can pin data for you in the IPFS network, so that it remains available even if you’re not actively seeding yourself (e.g. you turn off your laptop). They may also provide a point of backup for your data.

We have developed our own pinning service for Radicle projects, that one can deploy as seed nodes for one’s projects. For example, the service can be deployed to DigitalOcean virtual machines to run continuously in the cloud, as a peer-to-peer style hosting service.