docs: instructions for enrolling a passkey

Reviewed-on: #1

.gitea/workflows/deploy.yml

@@ -56,6 +56,11 @@ jobs:
           if [ -n "${{ vars.PDS_PRIMARY_COLOR }}" ]; then
             echo "pds_primary_color: \"${{ vars.PDS_PRIMARY_COLOR }}\"" >> vars/main.yml
           fi
+          # Optional: email/SMTP
+          if [ -n "${{ secrets.SMTP_URL }}" ]; then
+            echo "pds_email_smtp_url: ${{ secrets.SMTP_URL }}" >> vars/main.yml
+          fi
+          echo "pds_email_from_address: techops@cosocial.ca" >> vars/main.yml
 
       - name: Run playbook
         run: |

README.md

@@ -168,6 +168,13 @@ Create an account:
 pdsadmin account create
 ```
 
+Enroll an operator (admin dashboard) passkey — prints a single-use link, expires in 15 minutes; open it on the operator hostname over HTTPS (passkeys are per-hostname and need a secure context). Rerun to enroll another device or recover after losing all passkeys:
+
+```bash
+cd /pds/operator
+sudo docker compose exec app node dist/cli.js enroll
+```
+
 ## Teardown
 
 Run on the server to remove everything, use with caution:
@@ -201,6 +208,8 @@ Auto-deploys on push to `main`. Set up these in Gitea repo settings (Settings >
 | `PDS_SERVICE_NAME` | *(optional)* PDS display name for branding |
 | `PDS_PRIMARY_COLOR` | *(optional)* Primary color (hex) for branding |
 
+Outgoing emails are sent from `techops@cosocial.ca` (fixed in the workflow).
+
 **Secrets** (sensitive credentials):
 
 | Secret | Description |
@@ -208,5 +217,6 @@ Auto-deploys on push to `main`. Set up these in Gitea repo settings (Settings >
 | `SSH_PRIVATE_KEY` | Private SSH key for the `sysadmin` user on the target server |
 | `OVH_S3_ACCESS_KEY` | OVH S3 access key for blob storage |
 | `OVH_S3_SECRET_KEY` | OVH S3 secret key for blob storage |
+| `SMTP_URL` | *(optional)* SMTP URL with credentials (e.g., `smtps://user:pass@smtp.example.com/`) |
 
 The workflow installs Ansible, writes the SSH key from a secret, generates `inventory.yml` and `vars/main.yml` from vars and secrets, and runs the playbook.

playbook.yml

@@ -253,7 +253,7 @@
 
     - name: Operator health check
       uri:
-        url: "https://operator.{{ pds_hostname }}/oauth/client-metadata.json"
+        url: "https://{{ pds_operator_hostname }}/oauth/client-metadata.json"
         method: GET
         status_code: 200
       retries: 5

templates/Caddyfile.j2

@@ -16,7 +16,7 @@
   reverse_proxy http://localhost:3000
 }
 {% if pds_operator_enabled is defined and pds_operator_enabled | bool %}
-operator.{{ pds_hostname }} {
+{{ pds_operator_hostname }} {
   log {
     output stdout
     format json

templates/pds-operator-compose.yaml.j2

@@ -13,6 +13,11 @@ services:
       - AUDIT_LOG_PATH=/data/audit.log
     ports:
       - "127.0.0.1:8787:8787"
+    # the host's /etc/hosts maps the PDS hostname to 127.0.1.1 (cloud-init
+    # manage_etc_hosts), which Docker propagates to container DNS — pin the
+    # real address so the operator can reach the PDS
+    extra_hosts:
+      - "{{ pds_hostname }}:{{ hostvars[inventory_hostname].ansible_default_ipv4.address }}"
     volumes:
       # bind mount keeps data under /pds — captured by the backup tarball
       - ./data:/data

templates/pds-operator.env.j2

@@ -5,4 +5,4 @@ RELAY_HOSTNAME=bsky.network
 SESSION_SECRET={{ pds_operator_session_secret }}
 PORT=8787
 APPVIEW_URL=https://bsky.app
-DASHBOARD_URL=https://operator.{{ pds_hostname }}
+DASHBOARD_URL=https://{{ pds_operator_hostname }}

vars/main.yml.example

@@ -55,3 +55,4 @@ pds_crawlers: https://relay.fire.hose.cam  # relay/crawler endpoint
 pds_operator_enabled: true
 pds_operator_repo: https://tangled.org/brookie.blog/pds-operator
 pds_operator_version: main
+pds_operator_hostname: pds-operator.cosocial.ca