readme

1 files changed, 94 insertions, 11 deletions

diff --git a/README.md b/README.md
index 094e6ce..fdd1787 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,104 @@
 # Communique
 
-Communique aims to be an activitypub platform that abstracts outboxes/inboxes away from 
-handler implementations.
+Communique is a self-hosted, automated content publishing platform for [ActivityPub](https://www.w3.org/TR/activitypub/) that runs as a single static binary. It handles all necessary (and annoying) ActivityPub stuff like inboxes, outboxes, HTTP request signing/verification, WebFinger, persistence, delivery, etc. Imagine [mastodon](https://github.com/mastodon/mastodon), but designed for scripting/bots.
 
-1) handlers are defined in a config file
-2) these are read into the registry which allows lookup by name or by fqdn
+# Demo
 
+With communique it's easy to expose an RSS/atom feed as an ActivityPub actor, which can be followed by any other actor in the fediverse (like from a mastodon account). Let's walk through a quick example to show how it works.
 
-# CGI
+## Example
 
-Communique uses CGI as the API between itself and your scripts. These scripts are only run **internally** and are never executed from a TCP request.
+Given a configuration file like this:
+        
+        domain = "https://example.com" 
+
+        [[handlers]]
+        name = "sample"
+        exec = "sample-cgi-handler.sh"
+        interval = "5s"
+        dedupWindow = "30s"
+
+And a `sample-cgi-handler.sh` like:
+
+        #!/bin/bash
+        echo "Content-type: application/atom+xml"
+        echo ""
+        echo '<feed xmlns="http://www.w3.org/2005/Atom">
+            <entry>
+            <content>example content</content>
+            </entry>
+        </feed>'
+        exit 0       
+
+Communique will execute `sample-cgi-handler.sh` every 5 seconds, deduplicating the extracted `<content/> for a period of 30 seconds. Any unique items that are found are are persisted and delivered to all actors that follow the actor created above.
+
+## Run locally
+
+Run the following steps to see the example above in action.
+
+1. Clone the repository
+
+        git clone https://git.capotej.com/capotej/communique
+
+2. Go to the directory 
+
+        cd communique
+
+3. Compile and run it (feel free to click Deny on any firewall warnings)
+
+        go run main.go
+
+4. In another terminal, you can now see the actor page
+
+        curl -H 'Accept: application/json' http://localhost:8080/actors/sample |  python3 -m json.tool  
+
+5. And their outbox
+
+        curl -H 'Accept: application/json' http://localhost:8080/actors/sample/outbox |  python3 -m json.tool  
+
+If this were running on a real domain, like "https://example.com", we would now be able to follow this actor at `@sample@example.com` from any ActivityPub service.
+
+# Installation
+
+1. Clone the repository
 
-## Response API
+        git clone https://git.capotej.com/capotej/communique
+
+2. Go to the directory 
+
+        cd communique
+
+3. Build it
+
+        go build
+
+4. Deploy the binary wherever you want
+
+        ./communique -c my-config.toml
+
+## Build Dependencies
+* Go 1.19 (or higher).
+
+## Runtime Dependencies
+* SSL/TLS Proxy (like apache2 or nginx with letsencrypt)
+
+## systemd template
+
+## proxy configuration
+
+### apache
+
+### nginx 
+coming soon
+
+## helm
+coming soon
+
+# API
+
+## Handler scripts
+
+Communique uses CGI as the API between itself and your scripts. These scripts are only run **internally** and are never executed from a TCP request.
 
 >     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
 >     NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
@@ -28,7 +115,3 @@ Your CGI script reponse MUST be of one of these content types:
 Your CGI script reponse MUST be an RSS or ATOM feed (or at least something [gofeed](https://github.com/mmcdole/gofeed) can parse)
 
 See `sample-cgi-handler.sh` for an example
-
-## Processing
-
-Communique will iterate through this collection of objects and add them to the outbox for the handler for that script, if they have not been posted in the last hour. **(TODO make the dedupe window configurable)**
\ No newline at end of file