atstack
Personal atproto services deployment handbook
Star
Fork
Watch
atstack docs architecture.md
3.2 kB · 89 lines
Markdown
at main

Architecture #

Goal #

Run a personal AT Protocol PDS so the account data repository is under our control while still using existing atproto services such as Bluesky's relay and AppView.

This deployment is intentionally not a full atproto network stack. It does not run a relay, AppView, or Ozone in the first phase.

Hostnames #

  • 3drx.top: existing blog domain and desired atproto handle.
  • pds.3drx.top: PDS service hostname.
  • _atproto.3drx.top: TXT record used to bind the handle 3drx.top to the account DID.

The PDS service is not hosted on the apex so the blog can continue to use 3drx.top.

Compute #

The PDS runs on a Google Compute Engine VM:

  • SSH access: ssh -i <ssh-key-path> <vm-user>@<vm-public-ip>
  • OS: Linux VM capable of running Docker and the official PDS installer
  • Disk: root disk stores /pds
  • Memory: small personal VM; add swap if memory is constrained

The VM root disk stores /pds. There is no separate persistent disk by design. Durability comes from scheduled R2 backups.

PDS State #

/pds contains sensitive and durable state, including:

  • pds.env
  • SQLite databases
  • account and repo state
  • sequencer state
  • admin password
  • PLC rotation and recovery material
  • service config and metadata
  • local certificate references or files, depending on deployment layout

R2 blob storage does not replace /pds. If the VM/root disk is lost, recovery requires restoring /pds from backup.

Blob Storage #

Live blobs/media should be stored in a private Cloudflare R2 bucket through the PDS S3-compatible blobstore configuration.

Expected env shape:

PDS_BLOBSTORE_DISK_LOCATION=
PDS_BLOBSTORE_S3_BUCKET=<pds-blob-bucket>
PDS_BLOBSTORE_S3_REGION=auto
PDS_BLOBSTORE_S3_ENDPOINT=https://<cloudflare-account-id>.r2.cloudflarestorage.com
PDS_BLOBSTORE_S3_FORCE_PATH_STYLE=true
PDS_BLOBSTORE_S3_ACCESS_KEY_ID=<r2-access-key-id>
PDS_BLOBSTORE_S3_SECRET_ACCESS_KEY=<r2-secret-access-key>

The bucket stays private. Clients access blobs through the PDS and app services, not directly through public R2 URLs.

Backups #

Backups archive the entire /pds directory and upload it to a separate R2 bucket or prefix. Backup credentials should be separate from live blobstore credentials where practical.

Recommended retention:

  • at least 7 daily backups
  • at least 4 weekly backups

Retention can be enforced through an R2 lifecycle rule or an external maintenance job. The backup script uploads and verifies archives; destructive pruning should be enabled only after restore testing.

TLS and Cloudflare #

pds.3drx.top is proxied through Cloudflare.

The VM should use a Cloudflare Origin CA certificate for pds.3drx.top, and Cloudflare SSL/TLS mode should be Full (strict).

Cloudflare Origin CA certificates are trusted by Cloudflare, not by normal browsers that connect directly to the origin. Keep the DNS record proxied unless replacing the origin certificate with a public CA certificate.

DNS #

Required records:

pds.3drx.top        A      <vm-public-ip>    proxied
_atproto.3drx.top   TXT    did=did:plc:<your-did>

No wildcard PDS handle records are required for the single-user deployment.