Getting Started

Installation

The Ringspace binary can be installed using cargo.

If you do not have Cargo/Rustup installed, visit here first.

cargo install ringspace

Rings

This section walks through ring management.

Create a New Ring

In a folder of your choosing, run ringspace ring add. You can add the optional parameters, or let the wizard walk you through it. Use the -f option to set this as the default ring (you can manage multiple rings). You can run ringspace ring set-default later if you forget. When you’re done, a new ringspace.db Sqlite3 database will exist in this folder. This will hold all the information about your rings and sites. When you run the server, you must run it from a directory with this file!

Launch the server

Run ringspace server to launch the server on port 8000 by default. It would be a good idea to run this behind a reverse proxy of some kind. This process should also probably be managed by a Systemd Service or similar persistence mechanism.

Important

The server currently only manages data for the default ring!

Invite Sites

Identify a site you want to join the ring! It could be yours, or someone else’s. Once both parties have Ringspace installed, run ringspace invite create -u https://new-site.com to create a new invite code. This invite code will be what you share with the other party. When they’re ready, they will make a join request with that code. Be aware that by default, invite codes expire in 72 hours! You can alter that with the ---expiration-hrs option on ringspace invite create.

Fetch Votes

Sites will vote on each other, and you need to collect that data. Schedule a job to run ringspace ring fetch-votes to reach out to all member sites and collect new vote information. Your server will provide updated manifests on demand, but the vote information must be collected.

Site manifests store only the most recent vote for a given vote subject. This is to prevent creep in the manifests, and to represent that voters can change their minds. However, the Ring has a cooldown period. New votes will not be accepted within 24 hours of a previous vote.

Sites

This section discusses site management from the perspective of a site owner, rather than a ring owner.

Create a New Site

To make a site instead of a ring, run ringspace site add. Again, use the option flags or the wizard to walk through the creation. Use -f to mark a site a default on creation, or run ringspace site set-default later.

You can create as many sites as you like!

Join a Ring

With an invite code in hand (see above), run ringspace site join-ring -c invite-code-here. Specify the site you’re joining to the ring as necessary with -u, otherwise the default site will be assumed. If successful, your database will be updated to show that site as a member of that ring, which will be reflected in new manifest creations.

Create a Manifest

You create a new manifest any time you make a change to the site, including:

• Votes
• Key Rotation

ringspace site manifest (with an optional -u for non-default sites) will print the manifest JSON to the terminal. Place this in a file called webrings.json in a folder called .well-known underneath the web root of your site. So the full path to the manifest is https://your-site.com/.well-known/webrings.json.

Vote on Sites

You can manually add a single vote with ringspace site vote, but the easier way to do this is ringspace site vote-wizard. The Vote Wizard fetches the ring manifest, looks for all current members, and prompts you for votes on all of them. This helps make sure everyone has votes for other members in their manifests!

Rotate Keys

If you need to rotate your published keys, run ringspace site rotae. A new keypair will be generated and your joined rings will be queried with the new key data and a signature made with the old key. If any rings fail to update, this command will revert the change on all successes, guaranteeing that there are no discrepancies between rings and your keys. Only after a full remote rotation will your local keys be changed.

Leave a Ring

If you want to depart a ring, it’s as simple as ringspace site leave-ring -r https://ring-url.com. The departure request will be processed on the ring server, and you’ll be marked as unenrolled. Your local membership record will be removed, but not the ring data itself (you might have other sites that are still members!).