Service: Bluesky Personal Data Server - EyevinnOSC/community GitHub Wiki
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.
- 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.
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.
| 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.
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.
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.
OSC supports wildcard domain mappings natively. You upload a wildcard TLS certificate and configure one DNS A record; no CDN is needed.
- Obtain a wildcard TLS certificate for
*.pds.example.comfrom a certificate authority (for example Let's Encrypt viacertbot --manual --preferred-challenges dns). - Register a wildcard domain in OSC with the certificate and private key.
- Create a wildcard A record in your DNS pointing
*.pds.example.comto the IP address returned by OSC. - Set
DnsNametopds.example.comwhen creating or updating the PDS instance (update-service-instance).
See the Custom Domains guide for the full steps.
If you prefer to front the PDS with a CDN:
- Register a root domain (for example
my.org) and decide the PDS name (for examplepds.my.org). - Create an SSL certificate for
*.pds.my.organdpds.my.org. - Create the PDS with
DnsNameset topds.my.org. - 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.
- Point DNS records
*.pds.my.organdpds.my.orgat 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.
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.