My experience setting up PDS with nginx reverse proxy

[Layoric]

I recently setup PDS within an existing docker setup and thought I'd better share what I put together in it is of any use to others doing the same. I use:

• Ubuntu as host OS
• nginx-proxy as reverse proxy
• Shared docker network so nginx proxy can setup TLS automatically

If this looks TL;DR, skip to bottom for outlined docker-compose.yml.

---

The provided compose.yaml was useful as a starting point but since I didn't need caddy (another reverse proxy) I needed to make some changes. Having a turn key docker compose is a good goal, but currently even with caddy included, its a bit unclear the steps needed to get it running. I've got a decent amount of experience with Docker, but watchtower was new to me, and it seems to impact all containers running on the same host, so I disabled it as well. Leave me with initially just:

services:
  pds:
    container_name: pds
    image: ghcr.io/bluesky-social/pds:0.4
    restart: unless-stopped
    volumes:
      - type: bind
        source: ./data/pds
        target: /pds
    env_file:
      - ./data/pds/pds.env

Environment Variables

Next I had trouble working out which environment variables were required, I came across this helpful post in an issue showing setting up pdsadmin as a separate container and post environment variables to use. To get my account fully working, I needed the following (credit to adamisafk).

PDS_ADMIN_EMAIL=[YOUR EMAIL]
PDS_ADMIN_PASSWORD=[YOUR ADMIN PASSWORD]
PDS_JWT_SECRET=[GENERATE WITH; openssl rand --hex 16]
PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX=[GENERATE WITH; openssl ecparam --name secp256k1 --genkey --noout --outform DER | tail --bytes=+8 | head --bytes=32 | xxd --plain --cols 32]
PDS_BLOBSTORE_DISK_LOCATION=/pds/blocks
PDS_BLOBSTORE_DISK_TMP_LOCATION=/pds/temp
PDS_BSKY_APP_VIEW_DID=did:web:api.bsky.app
PDS_BSKY_APP_VIEW_URL=https://api.bsky.app
PDS_CRAWLERS=https://bsky.network
PDS_DATA_DIRECTORY=/pds
PDS_DID_PLC_URL=https://plc.directory
PDS_HOSTNAME=[YOUR HOSTNAME]
PDS_REPORT_SERVICE_DID=did:plc:ar7c4by46qjdydhdevvrndac
PDS_REPORT_SERVICE_URL=https://mod.bsky.app
# Email config
PDS_EMAIL_SMTP_URL=smtps://<user>:<password>@host:port
PDS_EMAIL_FROM_ADDRESS=[YOUR SMTP EMAIL]

Email Connection String Issue

The connection string type SMTP config can be problematic for those services that use an @, so be sure to URL encode, eg myname%40provider.com as this works. The email integration I don't believe is strictly needed for your own server of 1, but being able to verify your email does remove the nag message in the app.

Invalid Handle

I hit the issue of Invalid Handle after signing up. This seems to be caused by the assumption of either a catch all routing being used for subdomains since when I created by host of bsky.mydomain.net, it also requires <username>.bsky.mydomain.net is valid and responds the same as the root domain. Since I only have myself on the server you can use settings like this for nginx-proxy in your docker-compose.yml.

    environment:
      - VIRTUAL_PORT=3000
      - VIRTUAL_HOST=bsky.mydomain.net,[user].bsky.mydomain.net
      - LETSENCRYPT_HOST=bsky.mydomain.net,[user].bsky.mydomain.net
      - LETSENCRYPT_EMAIL=[EMAIL]

If you need multiple, you'll likely need something like the following in your DNS config:

*.example.com.       CNAME  server.example.com.

You will also want to make sure your container is connecting to the same network as your reverse proxy, eg:

networks:
  default:
    name: nginx
    external: true

So in the end, a minimal config like the following should get people most of the way if they are using a similar setup:

Final Docker Compose

services:
  pds:
    container_name: pds
    image: ghcr.io/bluesky-social/pds:0.4
    restart: unless-stopped
    volumes:
      - type: bind
        source: ./data/pds
        target: /pds
    env_file:
      - ./data/pds/pds.env
    environment:
      - VIRTUAL_PORT=3000
      - VIRTUAL_HOST=[your.domain],[username].[your.domain]
      - LETSENCRYPT_HOST=[your.domain],[username].[your.domain]
      - LETSENCRYPT_EMAIL=[your email]

  bluesky:
    container_name: bluesky
    profiles: [admin]
    build:
      context: .
      dockerfile_inline: |
        FROM ghcr.io/bluesky-social/pds:0.4
        RUN apk add bash curl openssl jq
        RUN curl --silent --show-error --fail --output "/usr/local/bin/pdsadmin" "https://raw.githubusercontent.com/bluesky-social/pds/main/pdsadmin.sh"
        RUN chmod +x /usr/local/bin/pdsadmin
    restart: unless-stopped
    volumes:
      - ./data/pds:/pds
    env_file: ./data/pds/pds.env

networks:
  default:
    name: [your-proxy-network]
    external: true

Hope this helps others with a similar setup save a bit of time.

[jsapede]

Nice !
Was stuck with nginx, will have a try with you settings

[timoshawn]

@Layoric
Thanks for the post. Your compose file really helped me.
I'm getting an error when running pdsadmin account list
This is the returned error:
/tmp/pdsadmin.account.fIEMmC: line 43: column: command not found

I found this issue and someone suggests installing bsdmainutils
Is it possible to get that installed in the bluesky container via your compose file?
Or do you have another suggestion?

[Layoric]

You could try adding it to install with the other packages, eg:

      dockerfile_inline: |
        FROM ghcr.io/bluesky-social/pds:0.4
        RUN apk add bash curl openssl jq bsdmainutils
        RUN curl --silent --show-error --fail --output "/usr/local/bin/pdsadmin" "https://raw.githubusercontent.com/bluesky-social/pds/main/pdsadmin.sh"
        RUN chmod +x /usr/local/bin/pdsadmin

But I haven't tried this to confirm, as I didn't hit this issue.

[timoshawn]

didn't work for me.
Thanks for the quick reply though.

[ontheair81]

Just found your post after I was successfully setting up a PDS on my own (in a similar scenario). But thanks anyway!

Just one thing is left: How to redirect visitors from user.my.domain to bsky.app/profile/user.my.domain?
Or in my case, as I am the only user on this PDS, from my.domain to bsky.app/profile/my.domain?

Not really necessary, but would be nice to have. Any ideas how to do that?

[Layoric]

Probably easiest way would be to setup the redirect at the nginx-proxy level. Eg,

server {
    server_name user.my.domain;
    return 301 https://bsky.app/profile/user.my.domain;
}

[ontheair81]

Just tested it. With my.domain (= my Bluesky handle), not user.my.domain, as this is a single-user instance.

Redirect works as expected, but it is breaking the websocket connection. Tested with this tool, connecting to wss://my.domain/xrpc/com.atproto.sync.subscribeRepos?cursor=0

Looks like the redirect should just work on the top level (my.domain), but should not redirect other paths.
Sadly I don't know a lot about nginx reverse proxy, so I would be happy for some hints :-)