Service: Bluesky Personal Data Server - EyevinnOSC/community GitHub Wiki

Bluesky Personal Data Server

Bluesky Personal Data Server (serviceId bluesky-social-pds) is the self-hosted PDS of the AT Protocol (Authenticated Transfer Protocol), the open protocol behind the Bluesky social network. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 20 GiB of storage per instance. Source: bluesky-social/pds.

What it can do

  • Host your own Bluesky account and data: a PDS is the server that stores your data, distributes it, manages your identity and orchestrates requests to other services (relays and app views).
  • Let a user on one PDS migrate their account to another PDS.
  • Serve accounts under your own domain via a wildcard domain mapping or a CDN.
  • Send verification and notification emails (including two-factor authentication) through an SMTP relay.

Creating an instance

Create the admin password as a service secret first: create-service-secret with serviceId: "bluesky-social-pds", a secret name (for example pdsadmin) and the password as value. Then call create-service-instance with serviceId: "bluesky-social-pds". The instance name must be alphanumeric and at most 20 characters. The PDS has no dependencies on other OSC services.

{
  "name": "myblog",
  "AdminPassword": "{{secrets.pdsadmin}}"
}

Leave DnsName empty unless you have set up a custom domain (see below). Wait for the instance with wait-for-service-ready (or get-instance-status) and read the instance URL with describe-service-instance.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only, at most 20 characters.
AdminPassword Yes string, sensitive Administrative password for PDS admin operations and account management (PDS_ADMIN_PASSWORD in the PDS documentation). Used as the Basic auth password (user admin) for admin API calls, and with the goat CLI for commands such as goat pds admin account create and goat pds admin create-invites. Store it as a service secret and pass {{secrets.NAME}}.
DnsName No string Public DNS hostname for the PDS that clients use to connect (PDS_HOSTNAME in the PDS documentation), for example pds.example.com. Requires both the root domain and a wildcard (*.pds.example.com) pointing at the instance, through either an OSC wildcard domain or a CDN. Leave empty to use the default OSC instance hostname.
EmailSmtpUrl No string, sensitive in practice (can contain credentials) SMTP server URL used to send verification emails and other notifications (PDS_EMAIL_SMTP_URL). Formats: smtps://resend:<api_key>@smtp.resend.com:465/, smtps://username:[email protected]/, or smtp:///?sendmail=true. Percent-encode special characters in credentials. Needs a restart to take effect.
EmailFromAddress No string Sender address for emails sent by the PDS (PDS_EMAIL_FROM_ADDRESS), typically an address on your own domain such as [email protected]. Used together with EmailSmtpUrl; needed for email verification and account migration confirmation emails.

AdminPassword must be passed as a {{secrets.NAME}} reference to a service secret; a reference must be the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

Create an invitation code

An account needs an invitation code. Send an HTTP POST to <instance-url>/xrpc/com.atproto.server.createInviteCode with Basic auth, user admin and the administration password, and the JSON body:

{ "useCount": 1 }

The code in the response is the invitation code.

Create an account

In the Bluesky app, choose a custom hosting provider when registering and enter the PDS instance URL, then enter the invitation code, email and password. The handle will be a subdomain of the instance hostname.

Custom domain via OSC wildcard domains

OSC supports wildcard domain mappings natively. You upload a wildcard TLS certificate and configure one DNS A record; no CDN is needed.

  1. Obtain a wildcard TLS certificate for *.pds.example.com from a certificate authority (for example Let's Encrypt via certbot --manual --preferred-challenges dns).
  2. Register a wildcard domain in OSC with the certificate and private key.
  3. Create a wildcard A record in your DNS pointing *.pds.example.com to the IP address returned by OSC.
  4. Set DnsName to pds.example.com when creating or updating the PDS instance (update-service-instance).

See the Custom Domains guide for the full steps.

Custom domain with a CDN

If you prefer to front the PDS with a CDN:

  1. Register a root domain (for example my.org) and decide the PDS name (for example pds.my.org).
  2. Create an SSL certificate for *.pds.my.org and pds.my.org.
  3. Create the PDS with DnsName set to pds.my.org.
  4. Create a CDN distribution whose origin is the PDS instance URL and that uses the certificate. The CDN must send the origin host in the request to the origin.
  5. Point DNS records *.pds.my.org and pds.my.org at the CDN distribution.

AWS CloudFront example: request one public certificate for *.your.domain and your.domain in the us-east-1 Certificate Manager; create a distribution with that certificate and CNAMEs for both names; set a custom origin pointing at the instance; create two CNAME records in Route 53 for the distribution. Use a cache policy that includes the headers Authorization, x-forwarded-host, Access-Control-Request-Method, Access-Control-Request-Headers and all query strings, and an origin request policy that includes all cookies, all query strings and the headers Sec-WebSocket-Key, Sec-WebSocket-Version, Sec-WebSocket-Protocol, Sec-WebSocket-Accept, Sec-WebSocket-Extensions. Assign both policies to the default behavior.

Email

To enable email verification and two-factor authentication, set EmailSmtpUrl (an SMTP relay URL, for example an OSC relay service) and EmailFromAddress when creating the instance.

Resources

⚠️ **GitHub.com Fallback** ⚠️