remove hardcoded federation defaults, rewrite README quickstart
This commit is contained in:
notplants
108
README.md
108
README.md
@ -13,53 +13,45 @@
|
||||
|
||||
<!-- endmetadata -->
|
||||
|
||||
## About
|
||||
## Quickstart
|
||||
|
||||
A [Bluesky PDS](https://github.com/bluesky-social/pds) (Personal Data Server)
|
||||
is a self-hosted server for the AT Protocol, allowing you to own your social
|
||||
data and federate with the Bluesky network.
|
||||
1. `abra app new bluesky-pds` (do **not** use `--secrets` yet, see below)
|
||||
2. Generate secrets:
|
||||
|
||||
## Basic usage
|
||||
The JWT secret and admin password can be generated automatically:
|
||||
|
||||
1. Set up Docker Swarm and [`abra`]
|
||||
2. Deploy [`coop-cloud/traefik`]
|
||||
3. `abra app new bluesky-pds` (do **not** use `--secrets` yet, see below)
|
||||
4. `abra app config YOURAPPDOMAIN` - set `DOMAIN` to something that resolves to
|
||||
your Docker swarm box
|
||||
5. Generate the PLC rotation key and create secrets (see below)
|
||||
6. `abra app deploy YOURAPPDOMAIN`
|
||||
7. Verify the PDS is running: `curl https://YOURAPPDOMAIN/xrpc/_health`
|
||||
```bash
|
||||
abra app secret generate YOURAPPDOMAIN pds_jwt_secret v1
|
||||
abra app secret generate YOURAPPDOMAIN pds_admin_password v1
|
||||
```
|
||||
|
||||
## Generating secrets
|
||||
The PLC rotation key is a secp256k1 private key and must be generated
|
||||
manually:
|
||||
|
||||
The JWT secret and admin password can be generated automatically:
|
||||
```bash
|
||||
openssl ecparam --name secp256k1 --genkey --noout --outform DER | \
|
||||
tail --bytes=+8 | head --bytes=32 | xxd --plain --cols 32
|
||||
```
|
||||
|
||||
```bash
|
||||
abra app secret generate YOURAPPDOMAIN pds_jwt_secret v1
|
||||
abra app secret generate YOURAPPDOMAIN pds_admin_password v1
|
||||
```
|
||||
Then store it as a secret:
|
||||
|
||||
The PLC rotation key is a secp256k1 private key and must be generated manually:
|
||||
```bash
|
||||
abra app secret insert YOURAPPDOMAIN pds_plc_rotation_key v1 <THE_KEY_HEX>
|
||||
```
|
||||
|
||||
```bash
|
||||
openssl ecparam --name secp256k1 --genkey --noout --outform DER | \
|
||||
tail --bytes=+8 | head --bytes=32 | xxd --plain --cols 32
|
||||
```
|
||||
3. `abra app deploy YOURAPPDOMAIN`
|
||||
|
||||
Then store it as a secret:
|
||||
|
||||
```bash
|
||||
abra app secret insert YOURAPPDOMAIN pds_plc_rotation_key v1 <THE_KEY_HEX>
|
||||
```
|
||||
Verify the PDS is running: `curl https://YOURAPPDOMAIN/xrpc/_health`
|
||||
|
||||
## Account management
|
||||
|
||||
Create an account on your PDS:
|
||||
Create an account on your PDS (use the admin password you stored during secret
|
||||
generation):
|
||||
|
||||
```bash
|
||||
abra app run YOURAPPDOMAIN app -- \
|
||||
goat pds admin account create \
|
||||
--admin-password "$(abra app secret get YOURAPPDOMAIN pds_admin_password v1)" \
|
||||
--admin-password YOUR_ADMIN_PASSWORD \
|
||||
--handle user.YOURAPPDOMAIN \
|
||||
--email user@example.com \
|
||||
--password yourpassword
|
||||
@ -70,9 +62,24 @@ Create an invite code:
|
||||
```bash
|
||||
abra app run YOURAPPDOMAIN app -- \
|
||||
goat pds admin account create-invite \
|
||||
--admin-password "$(abra app secret get YOURAPPDOMAIN pds_admin_password v1)"
|
||||
--admin-password YOUR_ADMIN_PASSWORD
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Once you've created an account (see above), you can log in with any
|
||||
ATProto-compatible client:
|
||||
|
||||
1. Open [bsky.app](https://bsky.app) (or another client like Graysky, Sky.app,
|
||||
etc.)
|
||||
2. On the login screen, tap **Hosting provider** (or **Custom PDS** depending on
|
||||
the client)
|
||||
3. Enter your PDS hostname: `YOURAPPDOMAIN`
|
||||
4. Log in with the handle and password you used when creating the account
|
||||
|
||||
Your handle will be `user.YOURAPPDOMAIN` by default (a subdomain handle). You
|
||||
can switch to a custom domain handle — see **Handle configuration** below.
|
||||
|
||||
## Handle configuration
|
||||
|
||||
User handles on a PDS can work in two ways:
|
||||
@ -86,6 +93,24 @@ User handles on a PDS can work in two ways:
|
||||
`did=did:plc:<their-did>`. This works without any additional server
|
||||
configuration.
|
||||
|
||||
## DNS setup
|
||||
|
||||
At minimum, create an A record pointing your PDS domain to your server:
|
||||
|
||||
```
|
||||
pds.example.com A <server-ip>
|
||||
```
|
||||
|
||||
For subdomain handles, also add a wildcard record:
|
||||
|
||||
```
|
||||
*.pds.example.com A <server-ip>
|
||||
```
|
||||
|
||||
[`abra`]: https://git.coopcloud.tech/coop-cloud/abra
|
||||
[`coop-cloud/traefik`]: https://git.coopcloud.tech/coop-cloud/traefik
|
||||
|
||||
|
||||
## TLS architecture (Caddy sidecar)
|
||||
|
||||
This recipe uses a **Caddy sidecar** for TLS instead of letting Traefik terminate
|
||||
@ -114,19 +139,12 @@ Caddy obtains the TLS certificate from Let's Encrypt. Subsequent requests are in
|
||||
No changes to the Traefik recipe are needed — the TCP passthrough is configured
|
||||
entirely via deploy labels on the Caddy service in this recipe's `compose.yml`.
|
||||
|
||||
## DNS setup
|
||||
## About
|
||||
|
||||
At minimum, create an A record pointing your PDS domain to your server:
|
||||
A [Bluesky PDS](https://github.com/bluesky-social/pds) (Personal Data Server)
|
||||
is a self-hosted server for ATProto. This is a co-op cloud recipe for a PDS
|
||||
as implemented by bluesky, although other pds implementations exist such as [rsky-pds](https://github.com/blacksky-algorithms/rsky/tree/main/rsky-pds).
|
||||
|
||||
```
|
||||
pds.example.com A <server-ip>
|
||||
```
|
||||
# ❃
|
||||
|
||||
For subdomain handles, also add a wildcard record:
|
||||
|
||||
```
|
||||
*.pds.example.com A <server-ip>
|
||||
```
|
||||
|
||||
[`abra`]: https://git.coopcloud.tech/coop-cloud/abra
|
||||
[`coop-cloud/traefik`]: https://git.coopcloud.tech/coop-cloud/traefik
|
||||
recipe maintained by @notplants
|
||||
|
||||
Reference in New Issue
Block a user