- TypeScript 56%
- Svelte 42%
- CSS 2%
- Docker <1%
- JavaScript <1%
- 1 more language <1%
Backyard #
Backyard is a social blogging platform built on the AT Protocol. It uses its own lexicon namespace (blue.backyard.*) for posts, comments, reblogs, likes, and follows, storing all user data in their Personal Data Server (PDS). Users log in via OAuth with scoped permissions.
Built with SvelteKit, PostgreSQL, Redis, and Docker.
Requirements #
- Node.js 22+
- PostgreSQL 18+ (with
pg_trgmextension) - Redis 8+ (for caching blobs)
- An internet-accessible domain with HTTPS (for OAuth callbacks)
Quick Start (Docker) #
The included docker-compose.yml runs the app, a PostgreSQL instance, and a Redis instance.
1. Generate secrets #
Generate an OAuth private key (ES256 / P-256 JWK):
node -e "const{generateKeyPairSync}=require('node:crypto');const{publicKey,privateKey}=generateKeyPairSync('ec',{namedCurve:'P-256'});const j=privateKey.export({format:'jwk'});j.alg='ES256';j.use='sig';console.log(JSON.stringify(j))"
Generate a session secret:
openssl rand -base64 48
2. Configure environment #
Copy .env.example to .env and set the required values:
| Variable | Required | Description |
|---|---|---|
INSTANCE_URL |
Yes | The public HTTPS URL of your instance (e.g. https://backyard.example.com) |
SESSION_SECRET |
Yes | Random string, 32+ characters. Used to encrypt session cookies. |
DATABASE_URL |
No | PostgreSQL connection string. Defaults to the bundled Compose database. |
OAUTH_PRIVATE_KEY_1 |
Yes | ES256 (P-256) private key in JWK format (see step 1). |
OAUTH_PRIVATE_KEY_2 |
No | Additional key for rotation. |
OAUTH_PRIVATE_KEY_3 |
No | Additional key for rotation. |
BODY_SIZE_LIMIT |
No | Maximum request body size in bytes. Defaults to 52428800 (50 MB) to support media uploads. |
BLOB_CACHE_DIR |
No | Filesystem path for caching fetched blobs. Defaults to ./blob-cache. Use an absolute path in Docker (e.g. /data/blob-cache). |
BLOB_CACHE_MAX_BYTES |
No | Maximum total size of the on-disk blob cache in bytes. Defaults to 2147483648 (2 GiB). |
REDIS_URL |
No | Redis connection URL (e.g. redis://redis:6379). When set, blobs are cached in Redis first; LRU entries evict to disk when BLOB_REDIS_MAX_BYTES is exceeded. When unset, blobs are cached on disk only. |
BLOB_REDIS_MAX_BYTES |
No | Maximum total size of the Redis blob cache in bytes. Defaults to 536870912 (512 MiB). |
JETSTREAM_URLS |
No | Comma-separated list of Jetstream WebSocket URLs in priority order. Backyard maintains connections to the top two available instances for redundancy. Defaults to wss://jetstream1.us-east.bsky.network/subscribe,wss://jetstream2.us-east.bsky.network/subscribe,wss://jetstream1.us-west.bsky.network/subscribe,wss://jetstream2.us-west.bsky.network/subscribe. |
JETSTREAM_DISABLED |
No | Set to true to disable the Jetstream consumer. |
SIGNUP_MODE |
No | open (default) or allowlist. Controls who can sign in to the instance. |
ADMIN_DIDS |
No | Comma-separated DIDs of instance admins. Required for /api/admin/* endpoints. |
HANDLE_RESOLVER_URL |
No | XRPC-compatible endpoint for resolving handles to DIDs. Falls back to https://public.api.bsky.app. A good choice is https://slingshot.microcosm.blue/. |
NEWS_DID |
No | DID of the account whose posts populate the news panel. If unset, resolves NEWS_HANDLE via the handle resolver. |
NEWS_HANDLE |
No | Handle of the news account. Defaults to backyard.blue. |
RAINBOW_URLS |
No | Comma-separated list of URLs for services implementing com.atproto.sync.listReposByCollection (e.g. Rainbow, Lightrail) used for backfill discovery at startup. Falls back to the next URL on error. Defaults to https://bsky.network. |
TOS_PATH |
No | Path to a plaintext or markdown file rendered at /terms_of_service. If set, users must agree before signing in. |
COMMUNITY_GUIDELINES_PATH |
No | Path to a plaintext or markdown file rendered at /community_guidelines. If set, users must agree before signing in. |
CAPTCHA_PDS_ALLOWLIST |
No | PDS Gatekeeper does not allow arbitrary captcha redirects by default. Put PDS hosts here that allow your instance to complete captchas. Comma-separated. |
In production, the app will refuse to start if SESSION_SECRET uses a default value or if no OAuth private key is configured.
3. Start #
docker compose up -d
The app listens on port 3000. Place it behind a reverse proxy (Nginx, Caddy, etc.) that terminates TLS and forwards to localhost:3000.
4. Verify #
Visit https://<your-domain>/oauth/client-metadata.json. Ensure that you see the OAuth client metadata document with your INSTANCE_URL and correct redirect URIs.
Navigating to https://<your-domain>/ should display the home feed.
Manual Setup (without Docker) #
npm ci
npm run build
Set the environment variables listed above, then:
NODE_ENV=production node build
You are responsible for running PostgreSQL separately and setting DATABASE_URL accordingly. The application creates its schema automatically on first startup.
Development #
npm install
npm run dev
No environment variable configuration is needed for local development. The app will use default values (local PostgreSQL at localhost:5432, ephemeral OAuth keys, default session secret). You must configure and run a local PostgreSQL instance yourself.
Architecture #
Backyard is a SvelteKit application using adapter-node. It does not store user content, except in the cache -- all posts, comments, reblogs, likes, and follows are atproto records written to each user's PDS.
PostgreSQL serves as a local index/cache of user records. Records arrive via two paths:
- Jetstream: real-time WebSocket stream of all
blue.backyard.*events across the network. - Startup backfill: on startup, the app queries a relay for all DIDs with records in any
blue.backyard.*collection, then backfills each one from their PDS. A cursor is stored in the database to avoid re-backfilling on subsequent restarts. - Per-user backfill: on login or profile view, missing records are fetched from the user's PDS via
com.atproto.repo.listRecords.
The database schema is created automatically at startup.
Lexicon #
All record types live under the blue.backyard namespace:
| Collection | Description |
|---|---|
blue.backyard.actor.profile |
User profile (display name, bio, avatar, banner) |
blue.backyard.feed.post |
Original post with text, rich text facets, media, and tags |
blue.backyard.feed.comment |
Comment on a post (threaded) |
blue.backyard.feed.reblog |
Reblog with optional text/tag additions |
blue.backyard.feed.like |
Like on a post |
blue.backyard.graph.follow |
Follow relationship |
blue.backyard.graph.block |
Block relationship |
blue.backyard.richtext.facet |
Rich text annotation (mentions, links, tags) |
Lexicon schemas are in the lexicons/ directory.
OAuth #
Authentication uses OAuth with scoped permissions. The app requests access only to the blue.backyard.* collections and blob uploads -- it does not request full account access. Key endpoints:
/oauth/client-metadata.json-- OAuth client metadata document/oauth/jwks.json-- Public keys forprivate_key_jwtauth/oauth/callback-- Authorization code callback
Reverse Proxy #
Backyard expects to run behind a TLS-terminating reverse proxy. A minimal Caddy configuration:
backyard.example.com {
reverse_proxy localhost:3000
}
For Nginx:
server {
listen 443 ssl;
server_name backyard.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Rate Limiting #
The application includes a basic in-memory rate limiter (60 writes/min, 300 reads/min per IP). This is per-process only and does not persist across restarts or scale across multiple instances. For production, enforce rate limiting at the reverse proxy or edge layer.
Signup Gating #
Backyard supports two signup modes, controlled by the SIGNUP_MODE environment variable:
open(default) -- anyone with an atproto account can sign in.allowlist-- only DIDs listed in the allowlist can sign in. Handles are automatically resolved to DIDs when added.
The login page adapts its messaging automatically based on the current mode.
Managing the allowlist #
Set ADMIN_DIDS to your DID, then use the admin UI while signed in.
You can add either a DID (did:plc:...) or a handle (alice.bsky.social). Handles are resolved to DIDs before storage, so the allowlist always contains DIDs. The check at sign-in time is DID-only.
Admin Moderation #
Admins can moderate content through web UI.
Banning users #
Admin users see moderation actions in context menus on posts and profiles. Banning a user prevents them from posting or interacting through the Backyard API. Banned users' posts are filtered from all feeds. All admin endpoints accept either a DID or a handle (handles are resolved to DIDs automatically).
Queued post deletion #
Instead of deleting posts from a user's PDS directly, admins queue posts for deletion. The offending post is immediately hidden from feeds, and the next time the author logs in they are shown a modal explaining the violation and requiring them to delete the post before they can continue using Backyard.
User Trust System #
Backyard includes an automatic trust scoring system that controls whether uploaded media is displayed. New accounts start untrusted and earn trust based on account age, existing AT Protocol activity, and posting frequency. Accounts scoring 50 or above out of 100 are considered "media trusted". Admins can manually override trust via the dashboard.