A community based topic aggregation platform built on atproto
bretton.dev
1# Aggregator Setup Scripts
2
3This directory contains scripts to help you set up and register your aggregator with Coves instances.
4
5## Overview
6
7Aggregators are automated services that post content to Coves communities. They are similar to Bluesky's feed generators and labelers. To use aggregators with Coves, you need to:
8
91. Create a PDS account for your aggregator (gets you a DID)
102. Prove you own a domain via `.well-known/atproto-did`
113. Register with a Coves instance
124. Create a service declaration record
13
14These scripts automate this process for you.
15
16## Prerequisites
17
18- **Domain ownership**: You must own a domain where you can host the `.well-known/atproto-did` file
19- **Web server**: Ability to serve static files over HTTPS
20- **Tools**: `curl`, `jq` (for JSON processing)
21- **Account**: Email address for creating the PDS account
22
23## Quick Start
24
25### Interactive Setup (Recommended)
26
27Run the scripts in order:
28
29```bash
30# Make scripts executable
31chmod +x *.sh
32
33# Step 1: Create PDS account
34./1-create-pds-account.sh
35
36# Step 2: Generate .well-known file
37./2-setup-wellknown.sh
38
39# Step 3: Register with Coves (after uploading .well-known)
40./3-register-with-coves.sh
41
42# Step 4: Create service declaration
43./4-create-service-declaration.sh
44```
45
46### Automated Setup Example
47
48For a reference implementation of automated setup, see the Kagi News aggregator at [aggregators/kagi-news/scripts/setup.sh](../../aggregators/kagi-news/scripts/setup.sh).
49
50The Kagi script shows how to automate all 4 steps (with the manual .well-known upload step in between).
51
52## Script Reference
53
54### 1-create-pds-account.sh
55
56**Purpose**: Creates a PDS account for your aggregator
57
58**Prompts for**:
59- PDS URL (default: https://bsky.social)
60- Handle (e.g., mynewsbot.bsky.social)
61- Email
62- Password
63
64**Outputs**:
65- `aggregator-config.env` - Configuration file with DID and credentials
66- Prints your DID and access tokens
67
68**Notes**:
69- Keep the config file secure! It contains your credentials
70- The PDS automatically generates a DID:PLC for you
71- You can use any PDS service, not just bsky.social
72
73### 2-setup-wellknown.sh
74
75**Purpose**: Generates the `.well-known/atproto-did` file for domain verification
76
77**Prompts for**:
78- Your domain (e.g., rss-bot.example.com)
79
80**Outputs**:
81- `.well-known/atproto-did` - File containing your DID
82- `nginx-example.conf` - Example nginx configuration
83- `apache-example.conf` - Example Apache configuration
84
85**Manual step required**:
86Upload the `.well-known` directory to your web server. The file must be accessible at:
87```
88https://yourdomain.com/.well-known/atproto-did
89```
90
91**Verify it works**:
92```bash
93curl https://yourdomain.com/.well-known/atproto-did
94# Should return your DID (e.g., did:plc:abc123...)
95```
96
97### 3-register-with-coves.sh
98
99**Purpose**: Registers your aggregator with a Coves instance
100
101**Prompts for**:
102- Coves instance URL (default: https://api.coves.social)
103
104**Prerequisites**:
105- `.well-known/atproto-did` must be accessible from your domain
106- Scripts 1 and 2 must be completed
107
108**What it does**:
1091. Verifies your `.well-known/atproto-did` is accessible
1102. Calls `social.coves.aggregator.register` XRPC endpoint
1113. Coves verifies domain ownership
1124. Inserts your aggregator into the `users` table
113
114**Outputs**:
115- Updates `aggregator-config.env` with Coves instance URL
116- Prints registration confirmation
117
118### 4-create-service-declaration.sh
119
120**Purpose**: Creates the service declaration record in your repository
121
122**Prompts for**:
123- Display name (e.g., "RSS News Aggregator")
124- Description
125- Source URL (GitHub repo, etc.)
126- Maintainer DID (optional)
127
128**What it does**:
1291. Creates a `social.coves.aggregator.service` record at `at://your-did/social.coves.aggregator.service/self`
1302. Jetstream consumer will index this into the `aggregators` table
1313. Communities can now discover and authorize your aggregator
132
133**Outputs**:
134- Updates `aggregator-config.env` with record URI and CID
135- Prints record details
136
137## Configuration File
138
139After running the scripts, you'll have an `aggregator-config.env` file with:
140
141```bash
142AGGREGATOR_DID="did:plc:..."
143AGGREGATOR_HANDLE="mynewsbot.bsky.social"
144AGGREGATOR_PDS_URL="https://bsky.social"
145AGGREGATOR_EMAIL="bot@example.com"
146AGGREGATOR_PASSWORD="..."
147AGGREGATOR_ACCESS_JWT="..."
148AGGREGATOR_REFRESH_JWT="..."
149AGGREGATOR_DOMAIN="rss-bot.example.com"
150COVES_INSTANCE_URL="https://api.coves.social"
151SERVICE_DECLARATION_URI="at://did:plc:.../social.coves.aggregator.service/self"
152SERVICE_DECLARATION_CID="..."
153```
154
155**Use this in your aggregator code** to authenticate and post.
156
157## What Happens Next?
158
159After completing all 4 steps:
160
1611. **Your aggregator is registered** in the Coves instance's `users` table
1622. **Your service declaration is indexed** in the `aggregators` table (takes a few seconds)
1633. **Community moderators can now authorize** your aggregator for their communities
1644. **Once authorized**, your aggregator can post to those communities
165
166## Creating an Authorization
167
168Authorizations are created by community moderators, not by aggregators. The moderator writes a `social.coves.aggregator.authorization` record to their community's repository.
169
170See `docs/aggregators/SETUP_GUIDE.md` for more information on the authorization process.
171
172## Posting to Communities
173
174Once authorized, your aggregator can post using:
175
176```bash
177curl -X POST https://api.coves.social/xrpc/social.coves.community.post.create \
178 -H "Authorization: DPoP $AGGREGATOR_ACCESS_JWT" \
179 -H "Content-Type: application/json" \
180 -d '{
181 "communityDid": "did:plc:...",
182 "post": {
183 "text": "Your post content",
184 "createdAt": "2024-01-15T12:00:00Z"
185 }
186 }'
187```
188
189## Troubleshooting
190
191### Error: "DomainVerificationFailed"
192
193- Verify `.well-known/atproto-did` is accessible: `curl https://yourdomain.com/.well-known/atproto-did`
194- Check the content matches your DID exactly (no extra whitespace)
195- Ensure HTTPS is working (not HTTP)
196- Check CORS headers if accessing from browser
197
198### Error: "AlreadyRegistered"
199
200- You've already registered this DID with this Coves instance
201- This is safe to ignore if you're re-running the setup
202
203### Error: "DIDResolutionFailed"
204
205- Your DID might be invalid or not found in the PLC directory
206- Verify your DID exists: `curl https://plc.directory/<your-did>`
207- Wait a few seconds and try again (PLC directory might be propagating)
208
209### Service declaration not appearing
210
211- Wait 5-10 seconds for Jetstream consumer to index it
212- Check the Jetstream logs for errors
213- Verify the record was created: Check your PDS at `at://your-did/social.coves.aggregator.service/self`
214
215## Example: Kagi News Aggregator
216
217For a complete reference implementation, see the Kagi News aggregator at `aggregators/kagi-news/`.
218
219The Kagi aggregator includes an automated setup script at [aggregators/kagi-news/scripts/setup.sh](../../aggregators/kagi-news/scripts/setup.sh) that demonstrates how to:
220
221- Automate the entire registration process
222- Use environment variables for configuration
223- Handle errors gracefully
224- Integrate the setup into your aggregator project
225
226This shows how you can package scripts 1-4 into a single automated flow for your specific aggregator.
227
228## Security Notes
229
230- **Never commit `aggregator-config.env`** to version control
231- Store credentials securely (use environment variables or secret management)
232- Rotate access tokens regularly
233- Use HTTPS for all API calls
234- Validate community authorization before posting
235
236## More Information
237
238- [Aggregator Setup Guide](../../docs/aggregators/SETUP_GUIDE.md)
239- [Aggregator PRD](../../docs/aggregators/PRD_AGGREGATORS.md)
240- [atProto Identity Guide](../../ATPROTO_GUIDE.md)
241- [Coves Communities PRD](../../docs/PRD_COMMUNITIES.md)
242
243## Support
244
245If you encounter issues:
246
2471. Check the troubleshooting section above
2482. Review the full documentation in `docs/aggregators/`
2493. Open an issue on GitHub with:
250 - Which script failed
251 - Error message
252 - Your domain (without credentials)