jaspermayone.com
@jaspermayone.com's dotfiles
1# Spindle Setup Guide
2
3This document outlines the Spindle CI/CD runner setup for alastor and dippet.
4
5## Overview
6
7Spindles are configured on two hosts:
8- **alastor** (NixOS, aarch64-linux): `1.alastor.spindle.hogwarts.dev`
9- **dippet** (macOS, aarch64-darwin): `1.dippet.spindle.hogwarts.dev`
10
11Both spindles are configured to run under the DID: `did:plc:abgthiqrd7tczkafjm4ennbo`
12
13## Alastor Setup (NixOS)
14
15### Configuration
16The alastor spindle is configured using the official Tangled nixosModule:
17
18- **Service**: `services.tangled.spindle`
19- **Listen Address**: `127.0.0.1:6555`
20- **Database**: `/var/lib/spindle/spindle.db` (default)
21- **Logs**: `/var/log/spindle` (default)
22- **Public URL**: `https://1.alastor.spindle.hogwarts.dev`
23
24### Deployment
25To deploy to alastor:
26
27```bash
28# From macOS (using deploy-rs)
29deploy .#alastor --skip-checks
30
31# Or via SSH
32ssh alastor
33cd ~/dots
34sudo nixos-rebuild switch --flake .#alastor
35```
36
37### Reverse Proxy
38Caddy is configured to proxy the spindle service with:
39- TLS via Cloudflare DNS challenge
40- HSTS headers
41- Proxying from port 443 to local port 6555
42
43### Monitoring
44The spindle service (`tangled-spindle`) is included in the status monitoring dashboard at `alastor.hogwarts.channel`.
45
46## Dippet Setup (macOS)
47
48### Configuration
49The dippet spindle is configured as a launchd daemon:
50
51- **Service**: `launchd.daemons.tangled-spindle`
52- **Listen Address**: `127.0.0.1:6556`
53- **Database**: `/Users/jsp/Library/Application Support/spindle/spindle.db`
54- **Logs**: `/Users/jsp/Library/Logs/spindle/`
55- **Public URL**: `https://1.dippet.spindle.hogwarts.dev` (requires tunnel setup)
56
57### Prerequisites
581. **Docker Desktop**: Added to homebrew casks - install with:
59 ```bash
60 brew install --cask docker
61 ```
62
632. **Cloudflare Tunnel**: Required for public access (see below)
64
65### Deployment
66To deploy to dippet:
67
68```bash
69# From dippet
70darwin-rebuild switch --flake ~/dev/dots#dippet
71
72# Or from remote
73ssh dippet 'cd ~/dev/dots && darwin-rebuild switch --flake .#dippet'
74```
75
76### Cloudflare Tunnel Setup (Using Existing Tunnel)
77
78Since you already have a running Cloudflare tunnel on dippet, you just need to add a route for the spindle service.
79
80#### Option 1: Using cloudflared CLI
81```bash
82# Add DNS route to your existing tunnel
83cloudflared tunnel route dns <your-tunnel-id> 1.dippet.spindle.hogwarts.dev
84```
85
86#### Option 2: Update tunnel config file
87If you're using a config file (usually at `~/.cloudflared/config.yml`), add the spindle ingress rule:
88
89```yaml
90tunnel: <your-tunnel-id>
91credentials-file: /path/to/credentials.json
92
93ingress:
94 # Add this entry
95 - hostname: 1.dippet.spindle.hogwarts.dev
96 service: http://localhost:6556
97
98 # Keep your existing rules here
99
100 # Catch-all rule (must be last)
101 - service: http_status:404
102```
103
104Then restart cloudflared:
105```bash
106sudo launchctl restart <your-cloudflared-service-name>
107```
108
109#### Option 3: Using Cloudflare Dashboard
1101. Go to Zero Trust > Networks > Tunnels
1112. Select your tunnel
1123. Go to Public Hostname tab
1134. Click "Add a public hostname"
1145. Set:
115 - Subdomain: `1.dippet.spindle`
116 - Domain: `hogwarts.dev`
117 - Service: `http://localhost:6556`
1186. Save
119
120### Verifying the tunnel
121After setup, verify the tunnel is running:
122
123```bash
124# Check tunnel status
125sudo launchctl list | grep cloudflared
126
127# Check logs
128tail -f ~/Library/Logs/cloudflared-spindle.log
129```
130
131## Service Management
132
133### Alastor (NixOS)
134```bash
135# Check status
136sudo systemctl status tangled-spindle
137
138# View logs
139sudo journalctl -u tangled-spindle -f
140
141# Restart
142sudo systemctl restart tangled-spindle
143
144# Stop
145sudo systemctl stop tangled-spindle
146```
147
148### Dippet (macOS)
149```bash
150# Check status
151sudo launchctl list | grep tangled-spindle
152
153# View logs
154tail -f ~/Library/Logs/spindle.log
155
156# Restart
157sudo launchctl kickstart -k system/org.nixos.tangled-spindle
158
159# Stop
160sudo launchctl stop org.nixos.tangled-spindle
161```
162
163## Testing
164
165Once both spindles are running and accessible, test them:
166
167```bash
168# Test alastor spindle
169curl https://1.alastor.spindle.hogwarts.dev
170
171# Test dippet spindle (after tunnel setup)
172curl https://1.dippet.spindle.hogwarts.dev
173```
174
175## Adding Spindles to Repositories
176
177To use these spindles for your repositories:
178
1791. Go to your repository settings on Tangled
1802. Navigate to the Spindles section
1813. Add the spindle hostnames:
182 - `1.alastor.spindle.hogwarts.dev`
183 - `1.dippet.spindle.hogwarts.dev`
184
185## Troubleshooting
186
187### Docker not available
188**Symptom**: Spindle fails to start containers
189
190**Solution**:
191- On alastor: Docker is managed by NixOS, check `sudo systemctl status docker`
192- On dippet: Ensure Docker Desktop is installed and running
193
194### Connection refused
195**Symptom**: Cannot connect to spindle endpoint
196
197**Solution**:
198- Check if the service is running
199- Verify firewall rules (alastor: port 443 should be open)
200- For dippet: Verify Cloudflare tunnel is active
201
202### Pipeline failures
203**Symptom**: Pipelines fail to execute
204
205**Solution**:
206- Check spindle logs for errors
207- Verify Docker is running and accessible
208- Check disk space: `df -h`
209- Verify Nixery is accessible: `curl https://nixery.tangled.sh`
210
211### Database corruption
212**Symptom**: Spindle fails to start with database errors
213
214**Solution**:
215- Backup the database
216- On alastor: `/var/lib/spindle/spindle.db`
217- On dippet: `~/Library/Application Support/spindle/spindle.db`
218- Delete and restart the service (will create fresh database)
219
220## OpenBao Secrets (Optional)
221
222If you want to use OpenBao for secrets management instead of the default SQLite backend, refer to the [Tangled Spindle documentation](https://docs.tangled.org/spindles.html#secrets-with-openbao) for setup instructions.
223
224## Next Steps
225
2261. ✅ Deploy to alastor
2272. ⏳ Install Docker Desktop on dippet
2283. ⏳ Set up Cloudflare tunnel for dippet
2294. ⏳ Deploy to dippet
2305. ⏳ Test both spindles
2316. ⏳ Add spindles to your repositories
232
233## References
234
235- [Tangled Spindle Documentation](https://docs.tangled.org/spindles.html)
236- [Spindle Self-hosting Guide](https://docs.tangled.org/spindles.html#self-hosting-guide)
237- [Cloudflare Tunnel Documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)