summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2022-10-28 16:18:20 -0700
committerBryan Newbold <bnewbold@robocracy.org>2022-10-28 16:19:40 -0700
commitc7ac6c415565a09b2250218ccc53f17bdb01b256 (patch)
tree5d4ed8ce5a9cc83dce65ef85af2106c7673bc83f /README.md
parent3690739ff8c9c4d01d83aace3dbe03a790e56b17 (diff)
downloadadenosine-c7ac6c415565a09b2250218ccc53f17bdb01b256.tar.gz
adenosine-c7ac6c415565a09b2250218ccc53f17bdb01b256.zip
update top-level README
Diffstat (limited to 'README.md')
-rw-r--r--README.md94
1 files changed, 91 insertions, 3 deletions
diff --git a/README.md b/README.md
index 8e881d9..f7bfea3 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,98 @@
</a>
</div>
-`adenosine`: hobby implementation of atproto.com in Rust
-========================================================
+`adenosine`: enthusiast-grade implementation of atproto.com in Rust
+===================================================================
-It doesn't work yet.
+**Status:** it doesn't even work yet and will eat your data
+
+This is a hobby project to implement components of the proposed Bluesky AT
+Protocol ([atproto.com](https://atproto.com)) for federated social media, as
+initially announced in Fall 2022. This might be interesting for other folks to
+take a spin with, but isn't intended to host real content from real people. The
+goal is to think through how the protocol might work by implementing it.
+
+
+## Quickstart (CLI)
+
+To work with an actual PDS server, you will need to get the
+[`bluesky-social/atproto`](https://github.com/bluesky-social/atproto) prototype
+PDS up and running locally. There is a separate
+[quickstart](./notes/atproto_quickstart.md) on how to get that going.
+
+If you run a Debian-base Linux distribution, you might be able to install an
+existing package (TODO: link). Otherwise, you'll need to build the CLI tool
+from source. Install a recent version of the Rust programming language
+toolchain (eg, using [`rustup`](https://rustup.rs/)
+
+The top level workplace includes the GUI and PDS code, which include huge
+dependency trees and are very slow to build. If you just want the CLI, enter
+the `adenosine-cli` directory before running any `cargo` commands.
+
+To build, test, and locally install just the CLI (using `cargo`):
+
+ cd adenosine-cli
+ cargo install
+
+To start interacting with a PDS, set the `ATP_HOST` environment variable. Then
+either register a test account, or create a new session for an existing
+account, and save the JWT token to the `ATP_AUTH_TOKEN`:
+
+ # default port for bluesky-social/atproto implementation
+ export ATP_HOST=http://localhost:2583
+
+ # register a new account
+ adenosine account register -u voltaire.test -p bogus -e voltaire@example.com
+ {
+ "did": "did:plc:yqtuksvatmmgngd5nkkw75hn",
+ "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjMwNn0.MMQa4JIQdwvhy-rjJ0kO-z8-KdoOL0Lto9JtOkK-lwE",
+ "username": "voltaire.test"
+ }
+
+ export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjMwNn0.MMQa4JIQdwvhy-rjJ0kO-z8-KdoOL0Lto9JtOkK-lwE
+
+ # to clear the auth token env variable
+ unset ATP_AUTH_TOKEN
+
+ # create a new session (login) for existing account
+ adenosine account login -u voltaire.test -p bogus
+ {
+ "did": "did:plc:yqtuksvatmmgngd5nkkw75hn",
+ "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjQxNX0.j2wcF1g9NxT_1AvYRiplNf_jtK6S81y3L38AkcBwOqY",
+ "name": "voltaire.test"
+ }
+
+ export ATP_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6cGxjOnlxdHVrc3ZhdG1tZ25nZDVua2t3NzVobiIsImlhdCI6MTY2Njk5NjQxNX0.j2wcF1g9NxT_1AvYRiplNf_jtK6S81y3L38AkcBwOqY
+
+You could save the `ATP_HOST` and `ATP_AUTH_TOKEN` values in `~/.bashrc` so you
+don't need to enter them every time.
+
+Now you can start posting and poking around:
+
+ adenosine bsky post "gruel again for breakfast"
+ {
+ "cid": "bafyreig2aqlsg4arslck64wbo2hnhe6k2a4z3z2sjfzh3uapv3a4zjld7e",
+ "uri": "at://did:plc:yqtuksvatmmgngd5nkkw75hn/app.bsky.post/3jg5zkr322c2a"
+ }
+
+
+ adenosine ls at://voltaire.test
+ app.bsky.post
+
+There is a [manpage](./extra/adenosine.1.md) and [CLI-specific
+README](./adenosine-cli/README.md) with more details and examples.
+
+
+## Development
Mininum Supported Rust Version (MSRV) is currently 1.61, using 2021 Rust
Edition.
+
+Contributions, conversations, bug reports, and handwriten postcards are all
+welcome. As mentioned above this is a low-effort hobby project so high-touch
+support, feature requests, growth strategies, etc, probably will not be
+fielded.
+
+The source code license is AGPLv3. Please acknowledge this in any initial
+contributions, and also indicate whether and how you would like to be
+acknowledged as a contributor (eg, a name and optionally a URL).