Monorepo for Aesthetic.Computer
aesthetic.computer
1# PDS Management Scripts
2
3Collection of scripts for managing your Aesthetic Computer PDS instance.
4
5## Available Scripts
6
7### Deployment
8
9#### `deployment/digitalocean/deploy.fish`
10Main deployment script that provisions infrastructure on DigitalOcean.
11
12```bash
13cd /workspaces/aesthetic-computer/at/pds/deployment/digitalocean
14fish deploy.fish
15```
16
17**What it does:**
18- Creates SSH key
19- Provisions Spaces bucket
20- Creates droplet
21- Configures firewall
22- Installs PDS
23
24#### `deployment/digitalocean/generate-pds-env.fish`
25Generates PDS environment file from vault credentials.
26
27```bash
28fish generate-pds-env.fish [output-file]
29```
30
31#### `scripts/auto-sync-frontend.sh`
32Polls GitHub and auto-deploys configured frontend files into the PDS Caddy container.
33
34```bash
35# Local smoke test (from repo root)
36AC_FORCE=1 at/pds/scripts/auto-sync-frontend.sh
37```
38
39**Default file map:**
40- `at/index.html -> /data/www/index.html`
41- `at/user-page.html -> /data/www/user.html`
42- `at/media-modal.js -> /data/www/media-modal.js`
43- `at/media-records.js -> /data/www/media-records.js`
44
45**Configurable via env:**
46- `AC_FILE_MAP="at/index.html:index.html;at/user-page.html:user.html;at/media-modal.js:media-modal.js;at/media-records.js:media-records.js;at/landing-page.html:landing-page.html"`
47
48**Typical server install (cron every minute):**
49```bash
50# 1) SSH to server
51ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>
52
53# 2) Install dependencies (jq is required for commit diff checks)
54apt update && apt install -y curl jq git
55
56# 3) Copy script to server
57scp -i ~/.ssh/aesthetic_pds /workspaces/aesthetic-computer/at/pds/scripts/auto-sync-frontend.sh root@<SERVER_IP>:/root/auto-sync-frontend.sh
58ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP> 'chmod +x /root/auto-sync-frontend.sh'
59
60# 4) Add cron job
61ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP> '(crontab -l 2>/dev/null; echo "* * * * * /root/auto-sync-frontend.sh >> /var/log/at-frontend-sync.log 2>&1") | crontab -'
62```
63
64**How it behaves:**
65- Tracks latest deployed commit in `/var/lib/at-frontend-sync/last_deployed_sha`
66- Compares changed files between last deployed SHA and latest main SHA
67- Skips deploy if none of the mapped frontend files changed
68- Uses `docker cp` into `caddy:/data/www/*`
69- Runs health check against `https://at.aesthetic.computer/xrpc/_health`
70
71#### `at/scripts/deploy-at-frontend.sh`
72Manual one-shot deploy helper from local machine to PDS host.
73
74```bash
75# From repo root (uses defaults + ~/.ssh/aesthetic_pds)
76at/scripts/deploy-at-frontend.sh
77
78# Optional custom map
79AT_FRONTEND_FILE_MAP="at/index.html:index.html;at/user-page.html:user.html;at/media-modal.js:media-modal.js;at/media-records.js:media-records.js;at/landing-page.html:landing-page.html" \
80 at/scripts/deploy-at-frontend.sh
81```
82
83### Monitoring
84
85#### `scripts/health-check.sh`
86Comprehensive health check for your PDS instance.
87
88```bash
89# Local check
90./scripts/health-check.sh
91
92# On server (via cron)
93*/5 * * * * /root/health-check.sh >> /var/log/pds-health.log 2>&1
94```
95
96**Checks:**
97- HTTP health endpoint
98- WebSocket connectivity
99- SSL certificate expiry
100- DNS resolution
101- Response time
102
103### Backup
104
105#### `scripts/backup.sh`
106Backs up SQLite databases and configuration.
107
108```bash
109# Manual backup
110./scripts/backup.sh
111
112# Automated backup (add to crontab)
1130 2 * * * /root/backup.sh >> /var/log/pds-backup.log 2>&1
114```
115
116**Features:**
117- Consistent SQLite backups
118- Configuration backup
119- Compressed archives
120- Automatic cleanup (30 days)
121- Optional Spaces upload
122
123### Storage Management
124
125#### `scripts/storage-manager.fish`
126Manage DigitalOcean Spaces blob storage.
127
128```bash
129# Setup s3cmd configuration
130fish scripts/storage-manager.fish setup
131
132# Check usage and cost
133fish scripts/storage-manager.fish usage
134
135# List recent uploads
136fish scripts/storage-manager.fish recent 50
137
138# Test connectivity
139fish scripts/storage-manager.fish test
140
141# Backup blobs
142fish scripts/storage-manager.fish backup
143
144# Clean test files
145fish scripts/storage-manager.fish clean
146
147# Show CDN info
148fish scripts/storage-manager.fish cdn
149```
150
151## Setup Instructions
152
153### 1. Install Dependencies
154
155**Local machine:**
156```bash
157# macOS
158brew install doctl s3cmd
159
160# Linux
161apt install doctl s3cmd
162
163# Or use package manager of choice
164```
165
166**On server:**
167```bash
168apt install sqlite3 jq curl
169```
170
171### 2. Configure Authentication
172
173```bash
174# Initialize doctl
175doctl auth init
176# Enter DO token from vault
177
178# Configure s3cmd (or use storage-manager.fish setup)
179fish scripts/storage-manager.fish setup
180```
181
182### 3. Deploy PDS
183
184```bash
185cd /workspaces/aesthetic-computer/at/pds/deployment/digitalocean
186
187# Generate environment file
188fish generate-pds-env.fish
189
190# Review configuration
191cat ../../config/pds.env
192
193# Deploy
194fish deploy.fish
195```
196
197### 4. Set Up Monitoring
198
199```bash
200# Copy scripts to server
201scp -i ~/.ssh/aesthetic_pds scripts/health-check.sh root@<SERVER_IP>:/root/
202scp -i ~/.ssh/aesthetic_pds scripts/backup.sh root@<SERVER_IP>:/root/
203
204# SSH to server
205ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>
206
207# Make executable
208chmod +x /root/*.sh
209
210# Add to crontab
211crontab -e
212
213# Add these lines:
214*/5 * * * * /root/health-check.sh >> /var/log/pds-health.log 2>&1
2150 2 * * * /root/backup.sh >> /var/log/pds-backup.log 2>&1
216```
217
218## Common Tasks
219
220### Check PDS Health
221
222```bash
223# From local machine
224./scripts/health-check.sh
225
226# Or directly
227curl https://pds.aesthetic.computer/xrpc/_health
228```
229
230### View Logs
231
232```bash
233# SSH to server
234ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>
235
236# PDS logs
237docker logs pds --tail 100 --follow
238
239# Health check logs
240tail -f /var/log/pds-health.log
241
242# Backup logs
243tail -f /var/log/pds-backup.log
244```
245
246### Update PDS
247
248```bash
249# SSH to server
250ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>
251
252# Backup first
253/root/backup.sh
254
255# Update
256pdsadmin update
257
258# Verify
259docker logs pds --tail 50
260curl https://pds.aesthetic.computer/xrpc/_health
261```
262
263### Restore from Backup
264
265```bash
266# SSH to server
267ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>
268
269# Stop PDS
270systemctl stop pds
271
272# Restore databases
273cd /backups/pds
274tar xzf pds-backup-YYYYMMDD-HHMMSS.tar.gz
275cp *.sqlite /pds/
276
277# Start PDS
278systemctl start pds
279
280# Verify
281docker logs pds --tail 50
282```
283
284### Check Storage Usage
285
286```bash
287# From local machine
288fish scripts/storage-manager.fish usage
289
290# Output:
291# Storage Used: 45.23 GB
292# Objects: 1,234
293# Estimated Cost: $5.00/month
294```
295
296### Create Account
297
298```bash
299# SSH to server
300ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>
301
302# Create account directly
303pdsadmin account create
304
305# Or create invite code
306pdsadmin create-invite-code
307
308# List accounts
309pdsadmin account list
310```
311
312## Troubleshooting
313
314### Script Fails to Run
315
316```bash
317# Ensure executable
318chmod +x scripts/*.sh
319chmod +x scripts/*.fish
320chmod +x deployment/digitalocean/*.fish
321
322# Check dependencies
323which doctl s3cmd fish bash
324
325# Load vault environment
326source /workspaces/aesthetic-computer/aesthetic-computer-vault/at/deploy.env
327```
328
329### s3cmd Not Configured
330
331```bash
332# Use storage manager to set up
333fish scripts/storage-manager.fish setup
334
335# Or manually
336s3cmd --configure
337```
338
339### Health Check Fails
340
341```bash
342# Check DNS
343dig pds.aesthetic.computer A
344
345# Check server is running
346ssh root@<SERVER_IP> 'systemctl status pds'
347
348# Check firewall
349doctl compute firewall list
350
351# Check SSL
352echo | openssl s_client -servername pds.aesthetic.computer -connect pds.aesthetic.computer:443
353```
354
355### Backup Fails
356
357```bash
358# Check disk space
359ssh root@<SERVER_IP> 'df -h'
360
361# Check backup directory exists
362ssh root@<SERVER_IP> 'mkdir -p /backups/pds'
363
364# Check SQLite databases exist
365ssh root@<SERVER_IP> 'ls -lh /pds/*.sqlite'
366```
367
368## Automation Examples
369
370### Daily Health Report
371
372```bash
373# Add to crontab
3740 8 * * * /root/health-check.sh && mail -s "PDS Health Report" me@jas.life < /var/log/pds-health.log
375```
376
377### Weekly Storage Report
378
379```bash
380# Add to crontab on local machine
3810 9 * * 1 cd /workspaces/aesthetic-computer/at/pds && fish scripts/storage-manager.fish usage | mail -s "PDS Storage Report" me@jas.life
382```
383
384### Monthly Backup to External Storage
385
386```bash
387# Add to crontab on server
3880 3 1 * * /root/backup.sh && rclone copy /backups/pds/ gdrive:pds-backups/
389```
390
391## Security Notes
392
3931. **SSH Keys**: Never commit SSH keys. Store in `~/.ssh/` with 600 permissions.
3942. **Vault Files**: Keep vault files private. They contain API keys and secrets.
3953. **Script Permissions**: Only make scripts executable, not readable by others.
3964. **Backup Encryption**: Consider encrypting backups before uploading to external storage.
397
398```bash
399# Encrypt backup
400gpg --encrypt --recipient me@jas.life backup.tar.gz
401
402# Decrypt backup
403gpg --decrypt backup.tar.gz.gpg > backup.tar.gz
404```
405
406## Script Maintenance
407
408### Update Scripts from Git
409
410```bash
411cd /workspaces/aesthetic-computer
412git pull origin main
413
414# Copy updated scripts to server
415scp -i ~/.ssh/aesthetic_pds scripts/*.sh root@<SERVER_IP>:/root/
416```
417
418### Add Custom Scripts
419
420Create new scripts in `scripts/` directory and follow these conventions:
421
422- **Shell scripts**: Use `.sh` extension, start with `#!/usr/bin/env bash`
423- **Fish scripts**: Use `.fish` extension, start with `#!/usr/bin/env fish`
424- **Make executable**: `chmod +x scripts/your-script.sh`
425- **Document**: Add description and usage in this README
426
427## Contributing
428
429When adding new scripts:
430
4311. Test thoroughly in development
4322. Add usage documentation to this file
4333. Include error handling and logging
4344. Use vault configuration where possible
4355. Make scripts idempotent (safe to run multiple times)
436
437---
438
439**Last Updated**: October 9, 2025