Bluesky Labeler Starter Kit

Use this repository to get started with your own Bluesky Labeler. Click the "Use this template" button above to create a new repository, and then follow the instructions below.

As an example, this repository includes a labeler for setting your favorite of the five elements (Earth, Fire, Air, Water, Love) to your profile. You can edit the labels, descriptions, and other parameters in the src/constants.ts file.

Labeler Creation Steps

The process of creating a labeler requires a few different steps:

1. Turn your account into a labeler account (bunx @skyware/labeler setup)
2. Create the set of posts that people will interact with to set their labels (bun set-posts)
3. Add the labels to the labeler account itself (bun set-labels or bunx @skyware/labeler label add)
4. Create a server to host the labeler on and serve labels (bun run start)

Prerequisites

• Node.js 21 or later
• Bun

Setup

Clone the repo and run bun i to install the dependencies. This project uses Bun for package management.

Run bunx @skyware/labeler setup to convert an existing account into a labeler. You can exit after converting the account; there's no need to add the labels with the wizard. We'll do that from code.

Copy the .env.example file to .env and fill in the values:

DID=did:plc:xxx
SIGNING_KEY=xxx
BSKY_IDENTIFIER=xxx
BSKY_PASSWORD=xxx
PORT=4100
METRICS_PORT=4101
FIREHOSE_URL=wss://jetstream.atproto.tools/subscribe
CURSOR_UPDATE_INTERVAL=10000

A cursor.txt file containing the time in microseconds also needs to be present. If it doesn't exist, it will be created with the current time.

Fill out the label IDs, names, descriptions etc. in src/constants.ts to your heart's desire. Run bun set-posts to create/update all posts at once, then copy/paste the related post rkeys (record keys) into src/constants.ts. Run bun set-labels to create/update all labels at once.

Alternatively, create the posts by hand, edit src/constants.ts and use bunx @skyware/labeler label add to add the labels.

The server connects to Jetstream, which provides a WebSocket endpoint that emits ATProto events in JSON. There are many public instances available:

Hostname	Region
jetstream1.us-east.bsky.network	US-East
jetstream2.us-east.bsky.network	US-East
jetstream1.us-west.bsky.network	US-West
jetstream2.us-west.bsky.network	US-West

The server needs to be reachable outside your local network using the URL you provided during the account setup (typically using a reverse proxy such as Caddy):

labeler.example.com {
	reverse_proxy 127.0.0.1:4100
}

Metrics are exposed on the defined METRICS_PORT for Prometheus. This dashboard can be used to visualize the metrics in Grafana.

Start the project with bun run start.

You can check that the labeler is reachable by checking the /xrpc/com.atproto.label.queryLabels endpoint of your labeler's server. A new, empty labeler returns {"cursor":"0","labels":[]}.

Credits

• alice, creator of the Zodiac Sign Labels
• Juliet, author of the Pronouns labeler, whose code my labelers were originally based on
• futur, creator of the skyware libraries which make it easier to build things for Bluesky

---

Manual Azure VM Setup Instructions

Install zsh because I'm not a monster

sudo apt install zsh zplug

Optional configuration for zsh: (https://wiki.debian.org/Zsh)[https://wiki.debian.org/Zsh]

Prepare for installation

sudo apt update && sudo apt upgrade -y
sudo apt install git build-essential -y

Add node source for newer version as bookworm only installs v18

curl -fsSL https://deb.nodesource.com/setup_21.x | sudo -E bash -
sudo apt install nodejs -y

Check the versions

git --version
node -v
npm -v

Install Caddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo tee /usr/share/keyrings/caddy-stable-archive-keyring.gpg > /dev/null
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/deb/debian/caddy-stable.list' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Caddy Configuration

Create a Caddyfile Configuration:

• In the Caddy VM, create or edit the Caddyfile located in /etc/caddy/Caddyfile

Ensure Caddy is running as a service

sudo systemctl status caddy

my.domain.tld {
	reverse_proxy localhost:4100
}

Restart Caddy to apply the configuration

sudo systemctl restart caddy

### Install Bun curl -fsSL https://bun.sh/install | bash

Add

export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

source $HOME/.zshrc
bun -version

Clone your project

git clone https://

Install dependencies with bun

Bun i

Create A Record to point to the VM

Create an A record in your DNS provider to point to the VM's IP address.

Virtual Machine Port Configuration

Make sure to open the ports in the VM configuration for the Caddy server to work properly.

Name	Protocol	Port	Source	Destination
AllowAnyHTTPInbound	TCP	80	Any	Any
AllowAnyHTTPSInbound	TCP	443	Any	Any