aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 6fe1670de05a7e7cb0a0d5afb85e82b6699e4149 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
# Communique

Communique is a self-hosted, automated content publishing platform for [ActivityPub](https://www.w3.org/TR/activitypub/) that runs as a standalone binary. It handles all the necessary (and annoying) ActivityPub stuff like inboxes, outboxes, HTTP request signing/verification, WebFinger, persistence, delivery, etc. Imagine [mastodon](https://github.com/mastodon/mastodon), but bots instead of humans.

# 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.

## Example

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 persisted to our actors inbox and delivered to all actors that follow our actor.

## 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 and see its posts on our timeline.

# Installation

1. Clone the repository

        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
>     "OPTIONAL" in this document are to be interpreted as described in
>     RFC 2119.

Your CGI script MUST emit a valid CGI response.

Your CGI script reponse MUST be of one of these content types:

* `application/atom+xml`
* `application/rss+xml`

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