Contrails is an ATProto Feed Generator backed by Cloudflare Workers and Bluesky Search.

Fork or copy the repository and edit CONFIG.md to define your feed generator.

Deploy right from GitHub Actions to Cloudflare Workers.

The current release is 0.2.4 - fork v.2024.02.21.

Please refer to the following URL for the Japanese instructions: https://blog.usounds.work/posts/contrails-fork-manual/

• Bluesky Social account
• GitHub account (Sign up or Login)
• Cloudflare account (Sign up or Login)
• A moderate-to-high tolerance for adventure

1. Create a Cloudflare Worker
2. Create a Cloudflare API Token (the Edit Workers template is fine. And add permissions for 'Account', 'D1', and 'Edit'.)
3. Create a Bluesky App Password
4. Fork this repository
5. In your fork's Settings > Secrets and variables > Actions, set the following:

• Variable: BLUESKY_HANDLE
• Variable: CLOUDFLARE_ACCOUNT_ID
• Variable: CLOUDFLARE_WORKER_NAME
• Secret: BLUESKY_APP_PASSWORD
• Secret: CLOUDFLARE_API_TOKEN
• Secret: CLOUDFLARE_D1_ID (put dummy value such as 'dummmy')

6. Edit CONFIG.md in your fork
7. Go to Actions > 1. Check Requirements, select Run Workflow, refresh and wait for completion
8. Go to Actions > 4. Create D1 Shema, select Run Workflow, refresh and wait for completion
9. Go to Cloudfare D1 page, check contrails-auth database id (such as 59025902-5902-4b69-ac8e-a277052dummy001) , copy and update GitHub secret variables as CLOUDFLARE_D1_ID
10. Go to Actions > 2. Deploy to Cloudflare, select Run Workflow, refresh and wait for completion
11. Go to Actions > 3. Publish Feed Generator, select Run Workflow, refresh and wait for completion
12. Visit the BLUESKY_HANDLE profile, e.g. https://bsky.app/profile/jcsalterego.bsky.social and then the Feeds tab

The longer (and incomplete) instructions can be found in INSTALL.md.

The first step before any major upgrade is to make a copy of your markdown config file. Your best bet is to save it in a separate directory such as backup_configs/, or you will have to remember to set isEnabled to false so it doesn't get picked up as a live config!

In the event you'd like to pull in the latest changes into a fork of Contrails, GitHub has great documentation here: GitHub Docs: Syncing a fork

• fixed the issue causing errors when using 'exact match'.

• Improve UTF-8 compatibility
• Modify deleteFeedGenerator to truncate Recordname to 15 characters and convert it to lowercase.

• Fixed issue causing failure during execution of delete-feed-generator.

• Fix to prevent errors when using user search

• Change search API from search/posts to app.bsky.feed.searchPosts

• denyList support. #13

• FIX: publishFeedGenerator threw an error. #19

• FIX: Quoted phrases such as "blue sky" work again. This will require case-insensitive matches, e.g. blue sky, Blue Sky or BLUE SKY.

• +reposts and +replies support. Note: Reposts will not be attributed ("reposted by User").

• Pagination
• Safe Mode

• New search term type: Users

• New search term type: Pinned posts

• Multiple feed support
• Ignore blockquotes in CONFIG.md (to allow comments).

• Delete Feed Generator workflow

• Initial Release

Ed. Note: Bluesky Search is now called Palomar.

flowchart LR
    subgraph Bluesky
        PDS["PDS"]
    end
    subgraph GitHub
        subgraph MD_Config["CONFIG.md"]
            searchTerms
        end
        subgraph CloudflareDeploy["Cloudflare Deploy"]
            Worker_JS
            CloudflareApiToken("CLOUDFLARE_API_TOKEN")
            CloudflareAccountID("CLOUDFLARE_ACCOUNT_ID")
            CloudflareWorkerName("CLOUDFLARE_WORKER_NAME")
        end
        subgraph BlueskyDeploy["Bluesky Deploy"]
            PublishFeedGenerator
            BlueskyHandle("BLUESKY_HANDLE")
            BlueskyAppPassword("BLUESKY_APP_PASSWORD")
        end
        MD_Config --> Worker_JS["worker.js"]
        MD_Config --> PublishFeedGenerator["publishFeedGenerator.ts"]
    end
    subgraph "Cloudflare Worker"
        CloudflareWorker[worker.js]
    end
    CloudflareDeploy -->|Deploy to Cloudflare| CloudflareWorker
    BlueskyDeploy -->|Publish Feed Generator| PDS

sequenceDiagram
    actor CoffeeTeaLover
    participant Bluesky
    participant Cloudflare as Cloudflare Worker
    participant Bluesky Search
    CoffeeTeaLover->>+Bluesky: get Coffee&Tea custom feed
    Bluesky->>+Cloudflare: get Coffee&Tea custom feed
    Cloudflare->>+Bluesky Search: search "coffee" and "tea"
    Bluesky Search->>+Cloudflare: posts matching "coffee" and "tea"
    Cloudflare->>+Bluesky: IDs of posts matching "coffee" and "tea"
    Bluesky->>+CoffeeTeaLover: posts for Coffee&Tea custom feed

2-Clause BSD