modernleft-docs/Docker Images/bluesky-pds.md

---
title: bluesky-pds
draft: false
date: 2025-01-18
---

|                              |                                                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------- |
| Official bluesky-pds project | [GitHub - bluesky-social/pds](https://github.com/bluesky-social/pds)                           |
| Image on Forgejo             | [Forgejo](https://code.modernleft.org/gravityfargo/-/packages/container/bluesky-pds/latest)    |
| Image on Dockerhub           | [Dockerhub](https://hub.docker.com/r/gravityfargo/bluesky-pds)                                 |
| Image Source                 | [Forgejo](https://code.modernleft.org/gravityfargo/bluesky-pds-docker)                         |
| Issue Tracker                | [GitHub - gravityfargo/bluesky-pds-docker](https://github.com/gravityfargo/bluesky-pds-docker) |

```bash
docker pull code.modernleft.org/gravityfargo/bluesky-pds:latest
```

---

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](https://doc.traefik.io/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.

> [!NOTE] Custom Domain
> You do <u>not</u> need to setup a PDS to have a custom domain in your username. Bluesky provides [documentation](https://bsky.social/about/blog/4-28-2023-domain-handle-tutorial) for DNS setup.

> [!warning] Data Warning
> Before changing images, upgrading, or any other modification always backup your data!

### Requirements

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

```bash
Manjaro/Arch
sudo pacman -S jq
# Debian/Ubuntu
sudo apt install make xxd
```

### Setup

Generate secrets and add them to `.env` file.
See [example.env](https://code.modernleft.org/gravityfargo/bluesky-pds-docker/src/branch/main/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)

If you'd like to learn more about my docker setup, head over to ~~[[getting started|Docker - Getting Started]]~~

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.

> [!warning]
> The compose element `hostname` must be the same value as `PDS_HOSTNAME`.

![[traefik]]

Optionally, you can use the [[middleware|BlueskyHeaders]] middle ware to set headers.

---

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

![[standalone]]

### Unraid
While I do not use Unraid, a [user on Reddit](https://www.reddit.com/r/selfhosted/comments/1i4r4yb/comment/m7y561x/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button) has added this project to the [Unraid Appstore](https://unraid.net/community/apps?q=bluesky#r) I won't be providing any meaningful support for

Unraid does not include the `xxd` package. You'll need another Linux machine for that. I made [[Generate PDS_PLC_ROTATION_KEY|some instructions]] for using a temporary alpine container if that helps.
### Running Commands

Nothing has changed in this department, other than not needing `sudo`. The commands are the same as the upstream project. Such as

- [Creating an account using pdsadmin](https://github.com/bluesky-social/pds?tab=readme-ov-file#creating-an-account-using-pdsadmin)
- [Creating an account using an invite code](https://github.com/bluesky-social/pds?tab=readme-ov-file#creating-an-account-using-an-invite-code)

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

> [!danger] Update Warning
> Do not under any circumstances update the image using `pdsadmin update`. I have not tested this, and it may break the image. Submit an
> [issue to my repository](https://github.com/gravityfargo/bluesky-pds-docker) requesting an update,
> and I will update this image and pin the pds to the new version.

### Cloudflare DNS

After various testing, I have figured out two things.

1. In order for email verification to work, you cannot have the DNS Proxy enabled or `AAAA` records active.
2. After you have verified emails, and do not intend to use the email feature, you can re-enable the DNS Proxy and `AAAA` records.

![[cloudflare.png]]

## SMTP

I use protonmail for my SMTP server. You can use any SMTP server you like, but I figured I'd share this information.
These are the environment variables I use.

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