Doc: How to install with Node + Caddy (rather than Docker)

[coolaj86]

Take heart. This really isn't that complicated.

The install file does far more complicated things to configure Docker and such than is actually necessary to install and run the app normally.

This will be much faster, easier, and consume far fewer system resources, as well as be easier to debug, move between machines, update etc. All upside. No downside.

Table of Contents

1. (optional) Create a Storage Volume
2. DNS Setup
3. Node Install + Git Clone + pnpm
4. Configure ENVs DON'T PANIC
5. Test Run with Node
6. Install Caddy (optional)
7. Install System Services (Caddy + Node)

1. Storage Volume (optional)

You'll probably want to create and mount an expandable block volume (so that you don't have to migrate if you run out of space).

For me, I mounted 20gb (recommended in the docs) and made a link to /mnt/storage (in my case I can resize, but in your case you might have to mount a different volume and copy files):

# change permission to the current user (mine is 'app')
sudo chown -R "$(id -u -n)":"$(id -g -n)" /mnt/vol-sfo1-20g

# link to the generic name /mnt/storage (to prevent issues upgrading in the future)
sudo ln -s /mnt/vol-sfo1-20g /mnt/storage

# create the blocks folder
mkdir -p /mnt/storage/pds-data/blocks/

2. DNS Setup

Set A, ANAME, or ALIAS records from your domain to your IP.

3. Node v20 Install + Git Clone + Install

curl https://webi.sh/node@20 | sh
source ~/.config/envman/PATH.env

corepack enable

git clone https://github.com/bluesky-social/pds.git /mnt/storage/pds
pushd /mnt/storage/pds/service/
pnpm install --production --frozen-lockfile

4. Configure ENVs

This assumes that you're in /mnt/storage/pds/service/, or its equivalent.

This looks scary because it runs some commands to generate random passwords and keys. Fret not.

Just copy and paste. It'll work.

fn_generate_random_bytes() {
    openssl rand --hex 16
}

fn_generate_secp256k1_private_key() {
    # grabs the private key part of a secp256k1 DER (decoded PEM)
    # (the same as getting random bytes above, but twice as long, and validated on a ecdsa curve)
    openssl ecparam --name secp256k1 \
        --genkey --noout --outform DER |
        tail --bytes=+8 |
        head --bytes=32 |
        xxd --plain --cols 32
}

echo "PDS_HOSTNAME=bluesky.example.com
PDS_PORT=3000
NODE_ENV=production

PDS_JWT_SECRET='$(fn_generate_random_bytes)'
PDS_ADMIN_PASSWORD='$(fn_generate_random_bytes)'
PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX='$(fn_generate_secp256k1_private_key)'

PDS_DATA_DIRECTORY=/mnt/storage/pds-data/
PDS_BLOBSTORE_DISK_LOCATION=/mnt/storage/pds-data/blocks/
PDS_BLOB_UPLOAD_LIMIT=52428800

PDS_DID_PLC_URL=https://plc.directory
PDS_BSKY_APP_VIEW_URL=https://api.bsky.app
PDS_BSKY_APP_VIEW_DID=did:web:api.bsky.app
PDS_REPORT_SERVICE_URL=https://mod.bsky.app
PDS_REPORT_SERVICE_DID=did:plc:ar7c4by46qjdydhdevvrndac
PDS_CRAWLERS=https://bsky.network

LOG_ENABLED=true" >> pds.env

Be sure to update PDS_HOSTNAME and PDS_PORT accordingly, as well as PDS_DATA_DIRECTORY and PDS_BLOBSTORE_DISK_LOCATION, if needed.

5. Test Run

This assumes that you're in /mnt/storage/pds/service/, or its equivalent.

mkdir -p /mnt/storage/pds-data/blocks/
node --env-file ./pds.env --enable-source-maps ./index.js

curl http://localhost:3080/xrpc/_health

{"version":"0.4.67"}

6. Install Caddy + Serviceman + systemd units

Caddy manages HTTPS and reverse proxying.

curl https://webi.sh/caddy | sh
source ~/.config/envman/PATH.env

Your /mnt/storage/pds/Caddyfile will likely look like this:

{
       email [email protected]
       on_demand_tls {
               # same port as bluesky pds
               ask http://localhost:3000/tls-check
       }
}

*.bluesky.example.com, bluesky.example.com {
        tls {
                # so that subdomain certs are only loaded as-needed, when requested
                on_demand
        }
        # same port as bluesky pds
        handle /xrpc/* {
                reverse_proxy http://localhost:3000
        }
        handle /.well-known/atproto-did {
                # to use your domain as your handle
                # see https://bsky.social/about/blog/4-28-2023-domain-handle-tutorial
                respond "did:plc:xxxxxxxxxxxxxxxxxxxxxxxx" 200
        }
}

You can ask an LLM for help configuring it if you have special needs

Service Files

Install serviceman (to create systemd service unit templates):

curl https://webi.sh/serviceman | sh
source ~/.config/envman/PATH.env

Install the Node service:

# CHANGE to wherever you installed pds/service
pushd /mnt/storage/pds/service/

sudo env PATH="$PATH" serviceman add --name bluesky-pds --system --username "$(id -u -n)" -- \
    node --env-file ./pds.env --enable-source-maps ./index.js

sudo journalctl -xefu bluesky-pds

curl http://localhost:3000/xrpc/_health

Install the Caddy service:

# CHANGE to wherever you put your Caddyfile
pushd /mnt/storage/pds
touch ./caddy.env

sudo env PATH="$PATH" serviceman add --name caddy --system --username "$(id -u -n)" -- \
    caddy run --envfile ./caddy.env --config ./Caddyfile --adapter 'caddyfile'

sudo journalctl -xefu caddy

curl https://bluesky.example.com/xrpc/_health