Flake to setup a local env for atproto development
edouard.paris
1# AT Protocol Development Environment
2
3A Nix-based development environment for running AT Protocol services (PDS, PLC, Caddy proxy, and MailHog).
4
5## Prerequisites
6
71. **Install mkcert** (required for SSL certificate generation):
8 - On macOS: `brew install mkcert`
9 - On Linux: See [mkcert installation guide](https://github.com/FiloSottile/mkcert#installation)
10 - After installation, run: `mkcert -install`
11
122. **Add hosts file entries:**
13 ```
14 127.0.0.1 pds.example.org
15 127.0.0.1 plc.example.org
16 127.0.0.1 relay.example.org
17 ```
18
193. **Generate SSL certificates before first use:**
20 ```bash
21 nix run .#generate-certs
22 ```
23
24## Quick Start
25
261. **Enter the development environment:**
27 ```bash
28 nix develop
29 ```
30
312. **Start all services in tmux:**
32 ```bash
33 nix run .#all
34 ```
35 This will start all services in a single-column tmux pane layout:
36 - Pane 0: PLC server
37 - Pane 1: PDS server
38 - Pane 2: Caddy proxy
39 - Pane 3: AT Protocol Relay
40
413. **Add PDS host to the relay:**
42 ```bash
43 goat relay --relay-host=https://relay.example.org:8445 admin --admin-password=password host add "https://pds.example.org:8443"
44 ```
45
464. **Create an invite code:**
47 ```bash
48 scripts/create-invite.sh
49 ```
50
515. **Create a user account:**
52 ```bash
53 goat account create \
54 --pds-host=https://pds.example.org:8443 \
55 --password=password \
56 --email=hello@example.org \
57 --invite-code=pds-example-org:8443-xyldq-yrhxc \
58 --handle=edouard.pds.example.org
59 ```
60
616. **Verify the DID is registered:**
62 ```bash
63 goat plc --plc-host=https://plc.example.org data <your-did>
64 ```
65
667. **Login to your account:**
67 ```bash
68 goat account login \
69 --username=edouard.pds.example.org \
70 --app-password=password \
71 --pds-host=https://pds.example.org:8443
72 ```
73
748. **Create your first post:**
75 ```bash
76 goat bsky post "hello world!"
77 ```
78
79## Services
80
81- **Bluesky PDS**: https://pds.example.org:8443
82- **DID PLC**: https://plc.example.org:8444
83- **AT Protocol Relay**: https://relay.example.org:8445
84- **MailHog**: http://localhost:8025
85
86## Monitoring
87
88To monitor the AT Protocol relay firehose:
89```bash
90goat firehose --relay-host wss://relay.example.org:8445
91```
92
93This will show real-time events from the relay. You can run this in a separate terminal or tmux pane.
94
95## Management Commands
96
97- `tmux attach -t atproto` - Attach to the services session
98- `tmux kill-session -t atproto` - Stop all services
99- `nix run .#mailhog` - Start MailHog (run separately if needed)
100- `nix run .#generate-certs` - Generate SSL certificates
101
102## ⚠️ Security Warning
103
104**This environment uses a modified AT Protocol relay with SSRF protection disabled.**
105
106- The relay is built from a forked repository (`edouardparis/indigo`) with SSRF (Server-Side Request Forgery) protections disabled
107- Custom ports are allowed without restrictions
108- **This configuration is ONLY safe for local development environments**
109- **DO NOT use this relay configuration against external hosts or in production**
110- **DO NOT expose this relay to the internet**
111
112This setup is designed for controlled local testing where you need flexibility in network access that would normally be restricted for security reasons.