PDS Management Scripts#

Collection of scripts for managing your Aesthetic Computer PDS instance.

Available Scripts#

Deployment#

`deployment/digitalocean/deploy.fish`#

Main deployment script that provisions infrastructure on DigitalOcean.

cd /workspaces/aesthetic-computer/at/pds/deployment/digitalocean
fish deploy.fish

What it does:

Creates SSH key
Provisions Spaces bucket
Creates droplet
Configures firewall
Installs PDS

`deployment/digitalocean/generate-pds-env.fish`#

Generates PDS environment file from vault credentials.

fish generate-pds-env.fish [output-file]

`scripts/auto-sync-frontend.sh`#

Polls GitHub and auto-deploys configured frontend files into the PDS Caddy container.

# Local smoke test (from repo root)
AC_FORCE=1 at/pds/scripts/auto-sync-frontend.sh

Default file map:

at/index.html -> /data/www/index.html
at/user-page.html -> /data/www/user.html
at/media-modal.js -> /data/www/media-modal.js
at/media-records.js -> /data/www/media-records.js

Configurable via env:

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"

Typical server install (cron every minute):

# 1) SSH to server
ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>

# 2) Install dependencies (jq is required for commit diff checks)
apt update && apt install -y curl jq git

# 3) Copy script to server
scp -i ~/.ssh/aesthetic_pds /workspaces/aesthetic-computer/at/pds/scripts/auto-sync-frontend.sh root@<SERVER_IP>:/root/auto-sync-frontend.sh
ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP> 'chmod +x /root/auto-sync-frontend.sh'

# 4) Add cron job
ssh -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 -'

How it behaves:

Tracks latest deployed commit in /var/lib/at-frontend-sync/last_deployed_sha
Compares changed files between last deployed SHA and latest main SHA
Skips deploy if none of the mapped frontend files changed
Uses docker cp into caddy:/data/www/*
Runs health check against https://at.aesthetic.computer/xrpc/_health

`at/scripts/deploy-at-frontend.sh`#

Manual one-shot deploy helper from local machine to PDS host.

# From repo root (uses defaults + ~/.ssh/aesthetic_pds)
at/scripts/deploy-at-frontend.sh

# Optional custom map
AT_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" \
  at/scripts/deploy-at-frontend.sh

Monitoring#

`scripts/health-check.sh`#

Comprehensive health check for your PDS instance.

# Local check
./scripts/health-check.sh

# On server (via cron)
*/5 * * * * /root/health-check.sh >> /var/log/pds-health.log 2>&1

Checks:

HTTP health endpoint
WebSocket connectivity
SSL certificate expiry
DNS resolution
Response time

Backup#

`scripts/backup.sh`#

Backs up SQLite databases and configuration.

# Manual backup
./scripts/backup.sh

# Automated backup (add to crontab)
0 2 * * * /root/backup.sh >> /var/log/pds-backup.log 2>&1

Features:

Consistent SQLite backups
Configuration backup
Compressed archives
Automatic cleanup (30 days)
Optional Spaces upload

Storage Management#

`scripts/storage-manager.fish`#

Manage DigitalOcean Spaces blob storage.

# Setup s3cmd configuration
fish scripts/storage-manager.fish setup

# Check usage and cost
fish scripts/storage-manager.fish usage

# List recent uploads
fish scripts/storage-manager.fish recent 50

# Test connectivity
fish scripts/storage-manager.fish test

# Backup blobs
fish scripts/storage-manager.fish backup

# Clean test files
fish scripts/storage-manager.fish clean

# Show CDN info
fish scripts/storage-manager.fish cdn

Setup Instructions#

1. Install Dependencies#

Local machine:

# macOS
brew install doctl s3cmd

# Linux
apt install doctl s3cmd

# Or use package manager of choice

On server:

apt install sqlite3 jq curl

2. Configure Authentication#

# Initialize doctl
doctl auth init
# Enter DO token from vault

# Configure s3cmd (or use storage-manager.fish setup)
fish scripts/storage-manager.fish setup

3. Deploy PDS#

cd /workspaces/aesthetic-computer/at/pds/deployment/digitalocean

# Generate environment file
fish generate-pds-env.fish

# Review configuration
cat ../../config/pds.env

# Deploy
fish deploy.fish

4. Set Up Monitoring#

# Copy scripts to server
scp -i ~/.ssh/aesthetic_pds scripts/health-check.sh root@<SERVER_IP>:/root/
scp -i ~/.ssh/aesthetic_pds scripts/backup.sh root@<SERVER_IP>:/root/

# SSH to server
ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>

# Make executable
chmod +x /root/*.sh

# Add to crontab
crontab -e

# Add these lines:
*/5 * * * * /root/health-check.sh >> /var/log/pds-health.log 2>&1
0 2 * * * /root/backup.sh >> /var/log/pds-backup.log 2>&1

Common Tasks#

Check PDS Health#

# From local machine
./scripts/health-check.sh

# Or directly
curl https://pds.aesthetic.computer/xrpc/_health

View Logs#

# SSH to server
ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>

# PDS logs
docker logs pds --tail 100 --follow

# Health check logs
tail -f /var/log/pds-health.log

# Backup logs
tail -f /var/log/pds-backup.log

Update PDS#

# SSH to server
ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>

# Backup first
/root/backup.sh

# Update
pdsadmin update

# Verify
docker logs pds --tail 50
curl https://pds.aesthetic.computer/xrpc/_health

Restore from Backup#

# SSH to server
ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>

# Stop PDS
systemctl stop pds

# Restore databases
cd /backups/pds
tar xzf pds-backup-YYYYMMDD-HHMMSS.tar.gz
cp *.sqlite /pds/

# Start PDS
systemctl start pds

# Verify
docker logs pds --tail 50

Check Storage Usage#

# From local machine
fish scripts/storage-manager.fish usage

# Output:
# Storage Used: 45.23 GB
# Objects: 1,234
# Estimated Cost: $5.00/month

Create Account#

# SSH to server
ssh -i ~/.ssh/aesthetic_pds root@<SERVER_IP>

# Create account directly
pdsadmin account create

# Or create invite code
pdsadmin create-invite-code

# List accounts
pdsadmin account list

Troubleshooting#

Script Fails to Run#

# Ensure executable
chmod +x scripts/*.sh
chmod +x scripts/*.fish
chmod +x deployment/digitalocean/*.fish

# Check dependencies
which doctl s3cmd fish bash

# Load vault environment
source /workspaces/aesthetic-computer/aesthetic-computer-vault/at/deploy.env

s3cmd Not Configured#

# Use storage manager to set up
fish scripts/storage-manager.fish setup

# Or manually
s3cmd --configure

Health Check Fails#

# Check DNS
dig pds.aesthetic.computer A

# Check server is running
ssh root@<SERVER_IP> 'systemctl status pds'

# Check firewall
doctl compute firewall list

# Check SSL
echo | openssl s_client -servername pds.aesthetic.computer -connect pds.aesthetic.computer:443

Backup Fails#

# Check disk space
ssh root@<SERVER_IP> 'df -h'

# Check backup directory exists
ssh root@<SERVER_IP> 'mkdir -p /backups/pds'

# Check SQLite databases exist
ssh root@<SERVER_IP> 'ls -lh /pds/*.sqlite'

Automation Examples#

Daily Health Report#

# Add to crontab
0 8 * * * /root/health-check.sh && mail -s "PDS Health Report" me@jas.life < /var/log/pds-health.log

Weekly Storage Report#

# Add to crontab on local machine
0 9 * * 1 cd /workspaces/aesthetic-computer/at/pds && fish scripts/storage-manager.fish usage | mail -s "PDS Storage Report" me@jas.life

Monthly Backup to External Storage#

# Add to crontab on server
0 3 1 * * /root/backup.sh && rclone copy /backups/pds/ gdrive:pds-backups/

Security Notes#

SSH Keys: Never commit SSH keys. Store in ~/.ssh/ with 600 permissions.
Vault Files: Keep vault files private. They contain API keys and secrets.
Script Permissions: Only make scripts executable, not readable by others.
Backup Encryption: Consider encrypting backups before uploading to external storage.

# Encrypt backup
gpg --encrypt --recipient me@jas.life backup.tar.gz

# Decrypt backup
gpg --decrypt backup.tar.gz.gpg > backup.tar.gz

Script Maintenance#

Update Scripts from Git#

cd /workspaces/aesthetic-computer
git pull origin main

# Copy updated scripts to server
scp -i ~/.ssh/aesthetic_pds scripts/*.sh root@<SERVER_IP>:/root/

Add Custom Scripts#

Create new scripts in scripts/ directory and follow these conventions:

Shell scripts: Use .sh extension, start with #!/usr/bin/env bash
Fish scripts: Use .fish extension, start with #!/usr/bin/env fish
Make executable: chmod +x scripts/your-script.sh
Document: Add description and usage in this README

Contributing#

When adding new scripts:

Test thoroughly in development
Add usage documentation to this file
Include error handling and logging
Use vault configuration where possible
Make scripts idempotent (safe to run multiple times)

Last Updated: October 9, 2025