aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/federation/README.md8
-rw-r--r--docs/guides/federation/getting-started.md189
2 files changed, 197 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
new file mode 100644
index 0000000..5a6b227
--- /dev/null
+++ b/docs/guides/federation/README.md
@@ -0,0 +1,8 @@
+# Guides to a federated swarm
+
+How to start, run and use a swarm kept by parties that don't trust each other. The design
+([`federation.md`](../../federation.md)) says what the rules are; these say how to live
+by them, in its words.
+
+* [`getting-started.md`](getting-started.md): two parties start a federation, write,
+ read, and let a third one in.
diff --git a/docs/guides/federation/getting-started.md b/docs/guides/federation/getting-started.md
new file mode 100644
index 0000000..8ce4c19
--- /dev/null
+++ b/docs/guides/federation/getting-started.md
@@ -0,0 +1,189 @@
+# Getting started
+
+Two parties, tv and lass, start a federation, a node each; they write, read, and let a
+third party, makefu, in by their votes. What a party signs goes through its client,
+`continuum-party`; what a node does, through its options
+([`running-a-node.md`](running-a-node.md)). The words are the design's
+([`federation.md`](../../federation.md)).
+
+## Building
+
+```sh
+cargo build --release --features mycelium,federation
+```
+
+That builds the node, `continuum`, and the party's client, `continuum-party`, in
+`target/release/`. Any transport does ([`transports.md`](../../transports.md)).
+
+## A key for each party
+
+The version names each party's keys, and the party signs with them. The client reads an
+OpenSSH Ed25519 key without a passphrase:
+
+```sh
+ssh-keygen -t ed25519 -N '' -f tv.key
+cut -d' ' -f1,2 tv.key.pub # ssh-ed25519 AAAA…: the key as a version names it
+```
+
+Here one key does everything a party signs.
+
+## A node for each party
+
+Each node needs its node key, a user of its API, and its node ID, which the first
+version names before the federation starts. A node makes its key with
+`--node-key-create` and logs its ID before anything else (`Node identity`): start it so
+once, with nothing of a swarm, and stop it.
+
+```sh
+printf '%s' 'secret' | argon2 "$(openssl rand -hex 16)" -id -e | sed 's/^/tv:/' > htpasswd
+continuum --node-key-file node.key --node-key-create --htpasswd htpasswd --mycelium-enable
+# INFO Created a new node key: this is a new node node_id=continuum:5be1…
+```
+
+## The first version
+
+The founders write the first version together, as a file:
+
+```json
+{ "federation": 1, "number": 0, "changes": null,
+ "keys": { "tv": { "since": 0, "keys": ["ssh-ed25519 AAAA…"] },
+ "lass": { "since": 0, "keys": ["ssh-ed25519 AAAA…"] } },
+ "nodes": { "tv": { "since": 0, "nodes": ["continuum:5be1…"] },
+ "lass": { "since": 0, "nodes": ["continuum:9c07…"] } },
+ "rules": [ { "path": "home/{party}/**", "writer": "{party}" } ] }
+```
+
+Each party writes in its namespace (`home/tv/…`), and nowhere else: no other rule gives
+a place. Every change of the version takes two thirds of its parties: of two, both.
+
+## The root
+
+```sh
+continuum-party root first.json > root
+```
+
+The federation's root, built byte for byte from the first version, and the file its
+nodes start from. Each founder makes it from the same version and finds the same bytes.
+The federation's ID is the root's SHA-256 (`store` in `GET /events`).
+
+## Records
+
+A party's client keeps a record of its party's votes, and votes by it (`--record`). A
+record begun at a node casts nothing on the version current then, as a vote sent before
+may be held back somewhere; one begun from the root, by a party that never voted, casts
+on every version, the first too:
+
+```sh
+continuum-party --record tv.record init tv --root root
+```
+
+Keep it: a party that loses its record casts nothing on the current version
+([`proposing-and-voting.md`](proposing-and-voting.md)).
+
+## Starting
+
+tv's node starts the federation from the root:
+
+```sh
+continuum --store-root root --store-party tv --store-file store.json \
+ --state-file state.json --document-file document --node-key-file node.key \
+ --htpasswd htpasswd --mycelium-enable
+curl -s -u tv:secret localhost:3000/events
+# {"checkpoint":"6d1e…","heads":["6d1e…"],"store":"6d1e…","taken":0}
+```
+
+lass's node joins it by its ID, through tv's node, one of whose addresses it is given
+(`addresses` in `GET /admin/stats` there):
+
+```sh
+continuum --store-id 6d1e… --store-party lass --store-file store.json \
+ --seeds mycelium:… --state-file state.json --document-file document \
+ --node-key-file node.key --htpasswd htpasswd --mycelium-enable
+```
+
+Nodes sync with the nodes the parties list, and with no others: both are in the first
+version.
+
+## Writing and reading
+
+tv writes in its namespace, through its node:
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
+ write home/tv/motd '"hello"'
+# 3a9f… taken
+```
+
+The value is JSON. lass reads it on its node, with everything else that counts:
+
+```sh
+curl -s -u lass:secret localhost:3000/events/counts | jq .values
+# {"home/tv/motd": "hello"}
+```
+
+lass can't write there: its node refuses it, as every node does.
+
+```sh
+continuum-party --node http://lass:secret@localhost:3000 --key lass.key \
+ --record lass.record write home/tv/motd '"mine"'
+# Error: the node answers 422 Unprocessable Entity: {"error":"the store refuses it",
+# "id":"…","why":"lass may not write at home/tv/motd"}
+```
+
+[`writing-and-reading.md`](writing-and-reading.md) has the rest.
+
+## Letting a party in
+
+makefu makes its key and its node as the founders did, and begins its record from the
+root, as it never voted:
+
+```sh
+continuum-party --record makefu.record init makefu --root root
+```
+
+The founders write the version letting makefu in: the next number, the hash of the
+version it changes (`.version.hash` in `GET /events/counts`), makefu's keys and node
+list named anew in it (`since` its number), and the founders' as they were:
+
+```json
+{ "federation": 1, "number": 1, "changes": "1f4c…",
+ "keys": { "tv": { "since": 0, "keys": ["ssh-ed25519 AAAA…"] },
+ "lass": { "since": 0, "keys": ["ssh-ed25519 AAAA…"] },
+ "makefu": { "since": 1, "keys": ["ssh-ed25519 AAAA…"] } },
+ "nodes": { "tv": { "since": 0, "nodes": ["continuum:5be1…"] },
+ "lass": { "since": 0, "nodes": ["continuum:9c07…"] },
+ "makefu": { "since": 1, "nodes": ["continuum:e2a8…"] } },
+ "rules": [ { "path": "home/{party}/**", "writer": "{party}" } ] }
+```
+
+One of them proposes it; the node shows the proposal by its hash, the version's:
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
+ propose second.json
+curl -s -u tv:secret localhost:3000/events/counts | jq '.proposals | keys'
+# ["8d02…"]
+```
+
+Both vote `true`, each through its own node:
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
+ vote 8d02… yes
+continuum-party --node http://lass:secret@localhost:3000 --key lass.key \
+ --record lass.record vote 8d02… yes
+```
+
+Once a node holds both votes, it writes the version, and every node takes it:
+`.version.number` in `GET /events/counts` is 1. makefu's node, started with
+`--store-id 6d1e… --store-party makefu` and a seed, is a member now: the others sync
+with it, and makefu writes in its namespace as tv did.
+
+## What next
+
+* [`running-a-node.md`](running-a-node.md): a node's options and files, and what it
+ does otherwise than in a swarm that isn't federated.
+* [`writing-and-reading.md`](writing-and-reading.md): places, values, and why a write
+ counts or doesn't.
+* [`proposing-and-voting.md`](proposing-and-voting.md): writing a version, proposing it,
+ and voting.