mackuba.eu
+63
-3
README.md
+63
-3
README.md
···
1
-
# Bluesky feeds in Ruby
1
+
<h1>Bluesky feeds in Ruby <img src="https://github.com/mackuba/bluesky-feeds-rb/assets/28465/81159f5a-82f6-4520-82c1-434057905a2c" style="width: 28px; margin-left: 5px; position: relative; top: 1px;"></h1>
2
2
3
3
This repo is an example or template that you can use to create a "feed generator" service for the Bluesky social network that hosts custom feeds. It's a reimplementation of the official TypeScript [feed-generator](https://github.com/bluesky-social/feed-generator) example in Ruby.
4
4
5
5
6
-
## How to use it
6
+
## How do feed generators work
7
+
8
+
**\#TODO** - please read the README of the official [feed-generator](https://github.com/bluesky-social/feed-generator) project.
9
+
10
+
11
+
## Setting up
12
+
13
+
First, you need to set up the database. By default, the app is configured to use SQLite and to create database files in `db` directory. If you want to use e.g. MySQL or PostgreSQL, you need to add a different database adapter gem to the [`Gemfile`](https://github.com/mackuba/bluesky-feeds-rb/blob/master/Gemfile) and change the configuration in [`config/database.yml`](https://github.com/mackuba/bluesky-feeds-rb/blob/master/config/database.yml).
14
+
15
+
To create the database, run the migrations:
16
+
17
+
```
18
+
bundle exec rake db:migrate
19
+
```
20
+
21
+
The feed configuration is done in [`app/config.rb`](https://github.com/mackuba/bluesky-feeds-rb/blob/master/app/config.rb). You need to set there:
7
22
8
-
\#TODO 🙃
23
+
- the DID identifier of the publisher (your account)
24
+
- the hostname on which the service will be running
25
+
26
+
Next, you need to create some feed classes in [`app/feeds`](https://github.com/mackuba/bluesky-feeds-rb/tree/master/app/feeds). See the included feeds like [`StarWarsFeed`](https://github.com/mackuba/bluesky-feeds-rb/blob/master/app/feeds/star_wars_feed.rb) as an example. The [`Feed`](https://github.com/mackuba/bluesky-feeds-rb/blob/master/app/feeds/feed.rb) superclass provides a `#get_posts` implementation which loads the posts in a feed in response to a request and passes the URIs to the server.
27
+
28
+
Once you have the feeds prepared, configure them in `app/config.rb`:
29
+
30
+
```rb
31
+
BlueFactory.add_feed 'starwars', StarWarsFeed.new
32
+
```
33
+
34
+
35
+
### Running in development
36
+
37
+
To run the firehose stream, use the [`firehose.rb`](https://github.com/mackuba/bluesky-feeds-rb/tree/master/firehose.rb) script. By default, it will save all posts to the database and print progress dots for every saved post, and will print the text of each post that matches any feed's conditions. See the options in the file to change this.
38
+
39
+
In another terminal window, use the [`server.rb`](https://github.com/mackuba/bluesky-feeds-rb/tree/master/server.rb) script to run the server. It should respond to such requests:
40
+
41
+
```
42
+
curl -i http://localhost:3000/.well-known/did.json
43
+
curl -i http://localhost:3000/xrpc/app.bsky.feed.describeFeedGenerator
44
+
curl -i http://localhost:3000/xrpc/app.bsky.feed.getFeedSkeleton?feed=at://did:plc:.../app.bsky.feed.generator/starwars
45
+
```
46
+
47
+
### Running in production
48
+
49
+
First, you need to make sure that the firehose script is always running and is restarted if necessary. One option to do this could be writing a `systemd` service config file and adding it to `/etc/systemd/system`.
50
+
51
+
To run the server part, you need an HTTP server and a Ruby app server. The choice is up to you and the configuration will depend on your selected config. My recommendation is Nginx with either Passenger (runs your app automatically from Nginx) or something like Puma (needs to be started by e.g. `systemd` like the firehose).
52
+
53
+
54
+
## Publishing the feed
55
+
56
+
Once you have the feed deployed to the production server, you can use the `bluesky:publish` Rake task (from the [blue_factory](https://github.com/mackuba/blue_factory) gem) to upload the feed configuration to the Bluesky network.
57
+
58
+
You need to make sure that you have configured the feed's metadata in the feed class:
59
+
60
+
- `display_name` (required) - the publicly visible name of your feed, e.g. "Star Wars Feed" (should be something short)
61
+
- `description` (optional) - a longer (~1-2 lines) description of what the feed does, displayed on the feed page as the "bio"
62
+
- `avatar_file` (optional) - path to an avatar image from the project's root (PNG or JPG)
63
+
64
+
When you're ready, run the rake task passing the feed key (you will be asked for the uploader account's password):
65
+
66
+
```
67
+
bundle exec rake bluesky:publish KEY=starwars
68
+
```
9
69
10
70
11
71
## Credits