retr0.id
A from-scratch atproto PDS implementation in Python (mirrors https://github.com/DavidBuchanan314/millipds)
1# Account Setup
2
3Once you've followed the setup instructions in the main README, your PDS should be accessible on the internet. Loading the index page should show some ASCII art and a "Hello" message.
4
5The next step is to create a user account.
6
7These instructions assume you are already familiar with atproto's DID mechanisms. TODO: don't assume that!
8
9Millipds does not hold did:plc rotation keys, and therefore it cannot make DID document updates on your behalf. This is good for security, and means that you can store your rotation keys offline.
10
11Millipds *does* however need to hold a repo signing key.
12
13Below, I assume you have two separate machines, the "server" (where the millipds server runs) and the "local machine". If you don't care about security (keeping rotation keys off the server) you can ignore that distinction and run all the commands on the server.
14
15## New Account (with did:plc)
16
17These instructions assume you're creating a user with handle `bob.example.com`, on a PDS at `https://pds.example.com` - replace them as appropriate!
18
19On the **local machine**:
20```sh
21git clone https://github.com/DavidBuchanan314/millipds
22cd millipds
23python3 -m pip install . # install the millipds command (use a venv if you want, I guess)
24./test_data/create_identity.sh bob.example.com https://pds.example.com https://plc.directory
25```
26
27Successful output should look something like this:
28```
29Generating keys...
30Submitting genesis op to PLC...
31OK
32
33Created identity for bob.example.com at https://plc.directory/did:plc:shnwoo25lrvyq3gijyjdmmal
34
35rotation key has been saved to bob.example.com_rotation_key.pem
36repo signing key has been saved to bob.example.com_repo_key.pem
37did:plc string has been logged to bob.example.com_did.txt
38
39Please store the rotation key somewhere especially safe!
40```
41
42Store `*_rotation_key.pem` very securely, this is the key to your whole atproto identity (feel free to give it a more descriptive file name).
43
44You'll need to copy `*_repo_key.pem` onto the server, however. (This key should also be kept secret, but if it's ever compromised or lost, you can replace it using the rotation key)
45
46Now, on the **server**:
47```sh
48sudo -u millipds -s
49source ~/.venv/bin/activate
50millipds account create did:plc:shnwoo25lrvyq3gijyjdmmal bob.example.com --signing_key=bob.example.com_repo_key.pem
51```
52
53Edit the DID per the one you just generated above, and the handle and signing key path likewise.
54
55You'll be prompted to enter a new password for the account, interactively. On success it should look something like this:
56
57```
58Password for new account:
59Confirm password:
60INFO:millipds.database:creating account for did=did:plc:shnwoo25lrvyq3gijyjdmmal, handle=bob.example.com
61```
62
63You also need to make sure the handle resolves. In this example, you'd create a TXT DNS record at `_atproto.bob.example` with value `did=did:plc:shnwoo25lrvyq3gijyjdmmal` (or use the .well-known method, see atproto docs. TODO: link)
64
65At this point, the account is created, and you should be able to log in through a client like `bsky.app`.
66
67You'll probably run into some error messages because the relay doesn't know about your PDS yet. This can be solved like so:
68
69```sh
70curl --json '{"hostname": "https://pds.example.com"}' "https://bsky.network/xrpc/com.atproto.sync.requestCrawl"
71```
72
73Now we need to emit an `#identity` event. This can be done by heading to your settings in `bsky.app` and "changing" your handle to the value it already is (e.g. `bob.example.com`) - this tells millipds to emit an `#identity` event. (I'll make this part more automatic in the future) (Note: as a temp workaround, this will also generate an `#account` event, which is maybe-necessary. unsure! In the future this should be triggered by account creation itself, probably.)
74
75The relay should be paying attention now, but maybe not the appview. To make the appview start indexing your posts, I *think* you need to create a bluesky profile record first, which can be done by setting your display name and/or bio (e.g. from `bsky.app`).
76
77Now, post something. If you're lucky, the relay and appview will pick it up, and now other people can see it. If not... have fun debugging...
78
79## New Account (with did:web)
80
81TODO (but it's conceptually not that different to did:plc, I bet you can figure it out!)
82
83## Inbound Migration
84
85TODO (millipds doesn't even support this yet, but one day it will)