retr0.id
A from-scratch atproto PDS implementation in Python (mirrors https://github.com/DavidBuchanan314/millipds)
account creation docs
+83
docs/ACCOUNTS.md
+83
docs/ACCOUNTS.md
···
1
+
# Account Setup
2
+
3
+
Once 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
+
5
+
The next step is to create a user account.
6
+
7
+
These instructions assume you are already familiar with atproto's DID mechanisms. TODO: don't assume that!
8
+
9
+
Millipds 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
+
11
+
It *does* however need to hold a repo signing key.
12
+
13
+
Below, 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 everything on the server.
14
+
15
+
## New Account (with did:plc)
16
+
17
+
These 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
+
19
+
On the **local machine**:
20
+
```sh
21
+
git clone https://github.com/DavidBuchanan314/millipds
22
+
cd millipds
23
+
python3 -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
+
27
+
Successful output should look something like this:
28
+
```
29
+
Generating keys...
30
+
Submitting genesis op to PLC...
31
+
OK
32
+
33
+
Created identity for bob.example.com at https://plc.directory/did:plc:shnwoo25lrvyq3gijyjdmmal
34
+
35
+
rotation key has been saved to bob.example.com_rotation_key.pem
36
+
repo signing key has been saved to bob.example.com_repo_key.pem
37
+
did:plc string has been logged to bob.example.com_did.txt
38
+
39
+
Please store the rotation key somewhere especially safe!
40
+
```
41
+
42
+
Store `*_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
+
44
+
You'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
+
46
+
Now, on the **server**:
47
+
```sh
48
+
sudo -u millipds -s
49
+
source ~/.venv/bin/activate
50
+
millipds account create did:plc:shnwoo25lrvyq3gijyjdmmal bob.example.com --signing_key=bob.example.com_repo_key.pem
51
+
```
52
+
53
+
Edit the DID per the one you just generated above, and the handle and signing key path likewise.
54
+
55
+
You'll be prompted to enter a new password for the account, interactively. On success it should look something like this:
56
+
57
+
```
58
+
Password for new account:
59
+
Confirm password:
60
+
INFO:millipds.database:creating account for did=did:plc:shnwoo25lrvyq3gijyjdmmal, handle=bob.example.com
61
+
```
62
+
63
+
You 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
+
65
+
At this point, the account is created, and you should be able to log in through a client like `bsky.app`.
66
+
67
+
You'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
70
+
curl --json '{"hostname": "https://pds.example.com"}' "https://bsky.network/xrpc/com.atproto.sync.requestCrawl"
71
+
```
72
+
73
+
Finally, we need to emit an `#identity` event (probably an `#account` event too but millipds doesn't do that yet!!!). 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)
74
+
75
+
Now, 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...
76
+
77
+
## New Account (with did:web)
78
+
79
+
TODO (but it's conceptually not that different to did:plc, I bet you can figure it out!)
80
+
81
+
## Inbound Migration
82
+
83
+
TODO (millipds doesn't even support this yet, but one day it will)
+10
-4
test_data/create_identity.sh
+10
-4
test_data/create_identity.sh
···
15
15
ROTATION_KEY_PATH="${HANDLE}_rotation_key.pem"
16
16
REPO_KEY_PATH="${HANDLE}_repo_key.pem"
17
17
GENESIS_JSON_PATH="${HANDLE}_plc_genesis.json"
18
+
DID_LOG_PATH="${HANDLE}_did.txt"
18
19
19
20
echo "Generating keys..."
20
21
···
30
31
--repo_pubkey=$(millipds util print_pubkey $REPO_KEY_PATH)
31
32
)
32
33
33
-
echo $DID_PLC > "${HANDLE}_did.txt"
34
+
echo $DID_PLC > $DID_LOG_PATH
34
35
35
36
echo "Submitting genesis op to PLC..."
36
37
···
38
39
39
40
curl --json @$GENESIS_JSON_PATH $PLC_URL
40
41
echo
41
-
42
-
echo "Created identity for ${HANDLE} at ${DID_PLC}"
43
-
echo $PLC_URL
42
+
echo
43
+
echo "Created identity for ${HANDLE} at ${PLC_URL}"
44
+
echo
45
+
echo "rotation key has been saved to ${ROTATION_KEY_PATH}"
46
+
echo "repo signing key has been saved to ${REPO_KEY_PATH}"
47
+
echo "did:plc string has been logged to ${DID_LOG_PATH}"
48
+
echo
49
+
echo "Please store the rotation key somewhere especially safe!"