diff options
| -rw-r--r-- | README.md | 105 |
1 files changed, 94 insertions, 11 deletions
@@ -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 |