bluesky-pds-docker/README.md

# bluesky-pds-docker

A self-contained Docker image for the [Bluesky PDS (Personal Data Server) ](https://github.com/bluesky-social/pds) for use with Traefik. This image is pinned to v0.4.74.

It is required to run the instance behind a proxy (like traefik) to generate SSL certificates. This will not work otherwise. The standard pds install includes caddy to handle this. A wildcard DNS assignment along with a wildcard SSL certificate is required. I use Cloudflare for this, see the screenshot below.

This is not intended for production, and I am not responsible for any data loss or security issues. This is a personal project, and I am not affiliated with Bluesky.

## Deployment

Before changing images or upgrading, backup the files made in the volume.

### Reqirements

I haven't verified these are the minimum requirements, but they are what I found to be necessary after starting this readme. I probably had some dependencies installed already.

#### Manjaro/Arch

```bash
sudo pacman -S jq
```

#### Debian/Ubunutu

```bash
sudo apt install make xxd
```

### Setup

Generate secrets and add them to `.env` file. See [example.env](example.env) as an example.

```bash
# Generate secret environment variables
echo PDS_ADMIN_PASSWORD: $(openssl rand --hex 16)

echo PDS_JWT_SECRET: $(openssl rand --hex 16)

echo PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX: $(openssl ecparam --name secp256k1 --genkey --noout --outform DER | tail --bytes=+8 | head --bytes=32 | xxd --plain --cols 32)
```

### Docker Compose Setup

Full list of additional Environment Variables provided by bluesky upstream can be found in the [packages/pds/src/config/env.ts](https://github.com/bluesky-social/atproto/blob/main/packages/pds/src/config/env.ts)

By default, the image uses 1000:1000 as the UID:GID for the user. This can be changed by setting the `PUID` and `PGID` environment variables.

The compose element `hostname` must be the same value as `PDS_HOSTNAME`.

#### Traefik

```yaml
# Traefik Proxy
services:
  bluesky-pds:
    container_name: bluesky-pds
    image: gravityfargo/bluesky-pds:0.4.74
    hostname: example.com
    extra_hosts:
      - "example.com:0.0.0.0" # domain:external_ip
    networks:
      - proxy
    environment:
      # Define variables here or in a .env file
      PDS_JWT_SECRET: ...
      PDS_ADMIN_PASSWORD: ...
      PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX: ...
      PDS_HOSTNAME: example.com
      PDS_EMAIL_SMTP_URL: smtps://resend:<your api key here>@smtp.resend.com:465/
      PDS_EMAIL_FROM_ADDRESS: admin@your.domain
      PUID: 1005
      PGID: 1005
    volumes:
      - ./bluesky-pds:/pds
    labels:
      traefik.enable: "true"
      traefik.http.routers.bluesky-pds-insecure.entrypoints: http
      traefik.http.routers.bluesky-pds-insecure.rule: HostRegexp(`^.+\.${URL_NAME}\.${URL_SUFFIX}$`) || Host(`${PDS_HOSTNAME}`)
      # traefik.http.routers.bluesky-pds-insecure.middlewares: BlueskyHeaders@file
      traefik.http.routers.bluesky-pds-secure.entrypoints: https
      traefik.http.routers.bluesky-pds-secure.rule: HostRegexp(`^.+\.${URL_NAME}\.${URL_SUFFIX}$`) || Host(`${PDS_HOSTNAME}`)
      traefik.http.routers.bluesky-pds-secure.tls: "true"
      traefik.http.services.bluesky-pds.loadbalancer.server.scheme: http
      traefik.http.services.bluesky-pds.loadbalancer.server.port: 3000
      # traefik.http.routers.bluesky-pds-secure.middlewares: BlueskyHeaders@file
```

#### Standalone

I do not run this, but it should be possible.

```yaml
# Standalone, you'll need to add a proxy in front of this with SSL.
services:
  bluesky-pds:
    container_name: bluesky-pds
    hostname: example.com
    extra_hosts:
      - "example.com:0.0.0.0" # domain:external_ip
    image: gravityfargo/bluesky-pds:0.4.74
    environment:
      # Define variables here or in a .env file
      PDS_JWT_SECRET: ...
      PDS_ADMIN_PASSWORD: ...
      PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX: ...
      PDS_HOSTNAME: example.com
      PDS_EMAIL_SMTP_URL: ""
      PDS_EMAIL_FROM_ADDRESS: ""
      PUID: 1005
      PGID: 1005
    volumes:
      - ./bluesky-pds:/pds
```

#### Middleware

I think file configs are cleaner than having a billion labels. This is not required, but it's nice to have.

```yaml
# middleware.yaml
http:
  middlewares:
    BlueskyHeaders:
      headers:
        accessControlAllowMethods:
          - GET
          - OPTIONS
          - PUT
          - POST
          - DELETE
        accessControlAllowHeaders: "*"
        accessControlAllowOriginList: "*"
        addVaryHeader: true
        stsSeconds: 63072000
```

#### Optional Proxy Network

```bash
docker network create --subnet=192.168.1.0/24 --ipv6 --attachable proxy
# /etc/docker/daemon.json
# {
#   "ipv6": true,
#   "fixed-cidr-v6": "2001:db8:1::/64"
# }

```

#### Cloudflare DNS

![alt text](assets/image.png)

#### Running Commands

```bash
docker exec -it bluesky-pds bash
pdsadmin account create
pdsadmin create-invite-code
```
#### Protonmail SMTP

`PDS_EMAIL_SMTP_URL: smtp://user@example.com:TOKEN@smtp.protonmail.ch:587/`
`PDS_EMAIL_FROM_ADDRESS: user@example.com`

## Development

The development enviornment must be behind a proxy to generate SSL certificates. This will not work otherwise. In my case, I use Traefik installed on a VPS that's dedicated to development.

I suggest buying a domain name for testing. I have one I use that's for a seperate project, but getting a throwaway domain is also an option. Millage may vary.

```bash
make generate-env
```

Then set the variables

- `PDS_HOSTNAME=example.com`
- `URL_NAME=example`
- `URL_SUFFIX=com`

Build the base image. This will take a while.

```bash
make build-base
```

Make edits as needed. Then build the dev image for testing.

```bash
make build-tag TAG=dev
```

Run the dev image.

```bash
make run
# or
docker-compose up
```