Flake to setup a local env for atproto development
Add relay
+64
-34
+45
-27
README.md
+45
-27
README.md
···
2
2
3
3
A Nix-based development environment for running AT Protocol services (PDS, PLC, Caddy proxy, and MailHog).
4
4
5
+
## ⚠️ Security Warning
6
+
7
+
**This environment uses a modified AT Protocol relay with SSRF protection disabled.**
8
+
9
+
- The relay is built from a forked repository (`edouardparis/indigo`) with SSRF (Server-Side Request Forgery) protections disabled
10
+
- Custom ports are allowed without restrictions
11
+
- **This configuration is ONLY safe for local development environments**
12
+
- **DO NOT use this relay configuration against external hosts or in production**
13
+
- **DO NOT expose this relay to the internet**
14
+
15
+
This setup is designed for controlled local testing where you need flexibility in network access that would normally be restricted for security reasons.
16
+
5
17
## Prerequisites
6
18
7
-
Make sure to add these lines to your `/etc/hosts` file:
8
-
```
9
-
127.0.0.1 pds.example.org
10
-
127.0.0.1 plc.example.org
11
-
127.0.0.1 relay.example.org
12
-
```
19
+
1. **Install mkcert** (required for SSL certificate generation):
20
+
- On macOS: `brew install mkcert`
21
+
- On Linux: See [mkcert installation guide](https://github.com/FiloSottile/mkcert#installation)
22
+
- After installation, run: `mkcert -install`
13
23
14
-
Generate SSL certificates before first use:
15
-
```bash
16
-
nix run .#generate-certs
17
-
```
24
+
2. **Add hosts file entries:**
25
+
```
26
+
127.0.0.1 pds.example.org
27
+
127.0.0.1 plc.example.org
28
+
127.0.0.1 relay.example.org
29
+
```
30
+
31
+
3. **Generate SSL certificates before first use:**
32
+
```bash
33
+
nix run .#generate-certs
34
+
```
18
35
19
36
## Quick Start
20
37
···
33
50
- Pane 2: Caddy proxy
34
51
- Pane 3: AT Protocol Relay
35
52
36
-
3. **Create an invite code:**
53
+
3. **Add PDS host to the relay:**
54
+
```bash
55
+
goat relay --relay-host=https://relay.example.org:8445 admin --admin-password=password host add "https://pds.example.org:8443"
56
+
```
57
+
58
+
4. **Create an invite code:**
37
59
```bash
38
60
scripts/create-invite.sh
39
61
```
40
62
41
-
4. **Create a user account:**
63
+
5. **Create a user account:**
42
64
```bash
43
65
goat account create \
44
66
--pds-host=https://pds.example.org:8443 \
···
48
70
--handle=edouard.pds.example.org
49
71
```
50
72
51
-
Expected output:
52
-
```
53
-
Success!
54
-
DID: did:plc:pzvsc3jwfjwidojtpbxv4rdd
55
-
Handle: edouard.pds.example.org
56
-
```
57
-
58
-
5. **Verify the DID is registered:**
73
+
6. **Verify the DID is registered:**
59
74
```bash
60
-
goat --plc-host=https://plc.example.org data did:plc:pzvsc3jwfjwidojtpbxv4rdd
75
+
goat plc --plc-host=https://plc.example.org data <your-did>
61
76
```
62
77
63
-
6. **Login to your account:**
78
+
7. **Login to your account:**
64
79
```bash
65
80
goat account login \
66
81
--username=edouard.pds.example.org \
···
68
83
--pds-host=https://pds.example.org:8443
69
84
```
70
85
71
-
7. **Create your first post:**
86
+
8. **Create your first post:**
72
87
```bash
73
88
goat bsky post "hello world!"
74
89
```
···
80
95
- **AT Protocol Relay**: https://relay.example.org:8445
81
96
- **MailHog**: http://localhost:8025
82
97
83
-
## Available Tools
98
+
## Monitoring
84
99
85
-
- `goat` - AT Protocol CLI tool
86
-
- `curl`, `jq` - HTTP and JSON utilities
87
-
- `tmux` - Terminal multiplexer
100
+
To monitor the AT Protocol relay firehose:
101
+
```bash
102
+
goat firehose --relay-host wss://relay.example.org:8445
103
+
```
104
+
105
+
This will show real-time events from the relay. You can run this in a separate terminal or tmux pane.
88
106
89
107
## Management Commands
90
108
+16
-4
flake.nix
+16
-4
flake.nix
···
98
98
tmux split-window -v -t atproto "${caddy-proxy}/bin/caddy-proxy"
99
99
100
100
# Split vertically for Relay (with environment variables)
101
-
tmux split-window -v -t atproto "RELAY_ADMIN_PASSWORD=password RELAY_PLC_HOST=https://plc.example.org:8444 RELAY_TRUSTED_DOMAINS=*.example.org RELAY_ALLOW_INSECURE_HOSTS=true ${indigo-relay}/bin/relay serve"
101
+
tmux split-window -v -t atproto "
102
+
export RELAY_ADMIN_PASSWORD=password
103
+
export RELAY_PLC_HOST=https://plc.example.org:8444
104
+
export RELAY_TRUSTED_DOMAINS=*.example.org
105
+
export RELAY_ALLOW_INSECURE_HOSTS=true
106
+
export RELAY_LOG_LEVEL=debug
107
+
export RELAY_DISABLE_SSRF=true
108
+
export RELAY_ALLOW_CUSTOM_PORTS=true
109
+
${indigo-relay}/bin/relay serve
110
+
"
102
111
103
-
# Make all panes equal size
104
-
tmux select-layout -t atproto even-vertical
105
112
106
113
# Select the first pane
107
114
tmux select-pane -t atproto.0
···
112
119
echo " tmux attach -t atproto - Attach to the session"
113
120
echo " tmux kill-session -t atproto - Stop all services"
114
121
echo ""
115
-
echo "📋 Panes layout (single column):"
122
+
echo "📋 Panes layout:"
116
123
echo " • Pane 0: PLC server"
117
124
echo " • Pane 1: PDS server"
118
125
echo " • Pane 2: Caddy proxy"
119
126
echo " • Pane 3: AT Protocol Relay"
120
127
echo ""
121
128
echo "💡 Use Ctrl+b followed by arrow keys to switch between panes"
129
+
echo "💡 To monitor firehose: goat firehose --relay-host wss://relay.example.org:8445"
122
130
'';
123
131
124
132
# Script to start relay with environment
···
135
143
export RELAY_PLC_HOST="https://plc.example.org:8444"
136
144
export RELAY_TRUSTED_DOMAINS="*.example.org"
137
145
export RELAY_ALLOW_INSECURE_HOSTS="true"
146
+
export RELAY_LOG_LEVEL="debug"
147
+
export RELAY_DISABLE_SSRF="true"
148
+
export RELAY_ALLOW_CUSTOM_PORTS="true"
138
149
139
150
${indigo-relay}/bin/relay serve
140
151
'';
···
171
182
echo " nix run .#plc - Start PLC server"
172
183
echo " nix run .#pds - Start PDS server"
173
184
echo " nix run .#caddy-proxy - Start Caddy proxy"
185
+
echo " nix run .#relay - Start AT Protocol Relay"
174
186
echo " nix run .#mailhog - Start MailHog"
175
187
echo " nix run .#generate-certs - Generate SSL certificates"
176
188
echo ""
+3
-3
packages/indigo-relay.nix
+3
-3
packages/indigo-relay.nix
···
8
8
version = "unstable-2024-10-03";
9
9
10
10
src = fetchFromGitHub {
11
-
owner = "bluesky-social";
11
+
owner = "edouardparis";
12
12
repo = "indigo";
13
-
rev = "master"; # Latest commit from master branch
14
-
hash = "sha256-yVj7DKGAUXQO4eTu4reAtm7bTE4ab0jYGX2ba74qazU=";
13
+
rev = "disable-ssrf-and-allow-custom-ports";
14
+
hash = "sha256-0Uy/7IT3gVVkfntXauue07O6WDhmU+heNT4fSh+sK5A=";
15
15
};
16
16
17
17
vendorHash = "sha256-7mYvgvR0tZdEnUgUYzKv6d2QyeXXnrFgVwY8/4UM3oU=";