mirrors/tranquil-pds
1
0
Fork 0
mirror of https://tangled.org/tranquil.farm/tranquil-pds synced 2026-04-24 18:30:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: small md file updates

Browse Source
This commit is contained in:
lewis
2026-02-11 18:16:38 +02:00
committed by Tangled
parent 91cfc536c6
commit a83a67d219
5 changed files with 76 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@@ -6,21 +6,19 @@ Bluesky runs on a federated protocol called AT Protocol. Your account lives on a
This particular PDS thrives under harsh conditions. It is a dandelion growing through the cracks in the sidewalk concrete.
It has full compatibility with Bluesky's reference PDS: same endpoints, same behavior, same client compatibility. Everything works: repo operations, blob storage, firehose, OAuth, handle resolution, account migration, the lot.
Another excellent PDS is [Cocoon](https://tangled.org/hailey.at/cocoon), written in go.
It has full compatibility with Bluesky's reference PDS.
## What's different about Tranquil PDS
It is a superset of the reference PDS, including: passkeys and 2FA (WebAuthn/FIDO2, TOTP, backup codes, trusted devices), SSO login and signup, did:web support (PDS-hosted subdomains or bring-your-own), multi-channel communication (email, discord, telegram, signal) for verification and alerts, granular OAuth scopes with a consent UI showing human-readable descriptions, app passwords with granular permissions (read-only, post-only, or custom scopes), account delegation (letting others manage an account with configurable permission levels), automatic backups (configurable retention and frequency, one-click restore), and a built-in web UI for account management, OAuth consent, repo browsing, and admin.
It is a superset of the reference PDS, including: passkeys and 2FA (WebAuthn/FIDO2, TOTP, backup codes, trusted devices), SSO login and signup, did:web support (PDS-hosted subdomains or bring-your-own), multi-channel communication (email, discord, telegram, signal) for verification and alerts, granular OAuth scopes with a consent UI showing human-readable descriptions, app passwords with granular permissions (read-only, post-only, or custom scopes), account delegation (letting others manage an account with configurable permission levels), and a built-in web UI for account management, repo browsing, and admin.
The PDS itself is a single small binary with no node/npm runtime. It requires postgres. Blobs are stored on the local filesystem by default (S3 optional). Valkey is optional (supported as an alternative to the built-in cache).
The PDS itself is a single binary with no nodeJS runtime. However, at time of writing, Tranquil requires postgres running separately. Blobs are stored on the local filesystem by default (S3 optional). Valkey is also optional (as an alternative to the built-in cache).
## Quick Start
```bash
cp .env.example .env
podman compose up -d
podman compose up db -d
just run
```
@@ -41,20 +39,18 @@ just lint
### Quick Deploy (Docker/Podman Compose)
Edit `.env.prod` with your values. Generate secrets with `openssl rand -base64 48`.
Edit `.env` with your values. Generate secrets with `openssl rand -base64 48`.
```bash
cp .env.prod.example .env.prod
cp .env.example .env
podman-compose -f docker-compose.prod.yaml up -d
```
### Installation Guides
| Guide | Best For |
|-------|----------|
| [Debian](docs/install-debian.md) | Debian 13+ with systemd |
| [Containers](docs/install-containers.md) | Podman with quadlets or OpenRC |
| [Kubernetes](docs/install-kubernetes.md) | You know what you're doing |
- [Debian](docs/install-debian.md)
- [Containers](docs/install-containers.md)
- [Kubernetes](docs/install-kubernetes.md)
## Maintainers to ping

90
docs/install-containers.md
View File

@@ -1,4 +1,4 @@
# Tranquil PDS Containerized Production Deployment
# Tranquil PDS containerized production deployment
This guide covers deploying Tranquil PDS using containers with podman.
@@ -7,13 +7,13 @@ This guide covers deploying Tranquil PDS using containers with podman.
## Prerequisites
- A VPS with at least 2GB RAM
- A server :p
- Disk space for blobs (depends on usage; plan for ~1GB per active user as a baseline)
- A domain name pointing to your server's IP
- A **wildcard TLS certificate** for `*.pds.example.com` (user handles are served as subdomains)
- Root or sudo access
- Root/sudo/doas access
## Quick Start (Docker/Podman Compose)
## Quickstart (docker/podman compose)
If you just want to get running quickly:
@@ -39,9 +39,13 @@ ln -sf live/pds.example.com/privkey.pem certs/privkey.pem
podman-compose -f docker-compose.prod.yaml restart nginx
```
The end!!!
Or wait, you want more? Perhaps a deployment that comes back on server restart?
For production setups with proper service management, continue to either the Debian or Alpine section below.
## Standalone Containers (No Compose)
## Standalone containers (no compose)
If you already have postgres running on the host (eg. from the [Debian install guide](install-debian.md)), you can run just the app containers.
@@ -91,25 +95,25 @@ See the [Debian install guide](install-debian.md) for the full nginx config with
---
# Debian 13+ with Systemd Quadlets
# Debian with systemd quadlets
Quadlets are the modern way to run podman containers under systemd.
Quadlets are a nice way to run podman containers under systemd.
## Install Podman
## Install podman
```bash
apt update
apt install -y podman
```
## Create Directory Structure
## Create the directory structure
```bash
mkdir -p /etc/containers/systemd
mkdir -p /srv/tranquil-pds/{postgres,blobs,backups,certs,acme,config}
```
## Create Environment File
## Create an environment file
```bash
cp /opt/tranquil-pds/.env.example /srv/tranquil-pds/config/tranquil-pds.env
@@ -121,9 +125,7 @@ Edit `/srv/tranquil-pds/config/tranquil-pds.env` and fill in your values. Genera
openssl rand -base64 48
```
For quadlets, also add `DATABASE_URL` with the full connection string (systemd doesn't support variable expansion).
## Install Quadlet Definitions
## Install quadlet definitions
Copy the quadlet files from the repository:
```bash
@@ -136,15 +138,13 @@ cp /opt/tranquil-pds/deploy/quadlets/tranquil-pds-nginx.container /etc/container
Optional quadlets for valkey and minio are also available in `deploy/quadlets/` if you need them.
Note: Systemd doesn't support shell-style variable expansion in `Environment=` lines. The quadlet files expect DATABASE_URL to be set in the environment file.
## Create nginx Configuration
## Create nginx configuration
```bash
cp /opt/tranquil-pds/nginx.frontend.conf /srv/tranquil-pds/config/nginx.conf
```
## Clone and Build Images
## Clone and build images
```bash
cd /opt
@@ -154,14 +154,14 @@ podman build -t tranquil-pds:latest .
podman build -t tranquil-pds-frontend:latest ./frontend
```
## Create Podman Secrets
## Create podman secrets
```bash
source /srv/tranquil-pds/config/tranquil-pds.env
echo "$DB_PASSWORD" | podman secret create tranquil-pds-db-password -
```
## Start Services and Initialize
## Start services and initialize
```bash
systemctl daemon-reload
@@ -169,13 +169,7 @@ systemctl start tranquil-pds-db
sleep 10
```
Run migrations:
```bash
cargo install sqlx-cli --no-default-features --features postgres
DATABASE_URL="postgres://tranquil_pds:your-db-password@localhost:5432/pds" sqlx migrate run --source /opt/tranquil-pds/migrations
```
## Obtain Wildcard SSL Certificate
## Obtain a wildcard SSL cert
User handles are served as subdomains (eg. `alice.pds.example.com`), so you need a wildcard certificate. Wildcard certs require DNS-01 validation.
@@ -209,13 +203,13 @@ ln -sf /srv/tranquil-pds/certs/live/pds.example.com/privkey.pem /srv/tranquil-pd
systemctl restart tranquil-pds-nginx
```
## Enable All Services
## Enable all services
```bash
systemctl enable tranquil-pds-db tranquil-pds-app tranquil-pds-frontend tranquil-pds-nginx
```
## Configure Firewall
## Configure firewall if you're into that sort of thing
```bash
apt install -y ufw
@@ -225,7 +219,7 @@ ufw allow 443/tcp
ufw enable
```
## Certificate Renewal
## Cert renewal
Add to root's crontab (`crontab -e`):
```
@@ -234,11 +228,11 @@ Add to root's crontab (`crontab -e`):
---
# Alpine 3.23+ with OpenRC
# Alpine with OpenRC
Alpine uses OpenRC, not systemd. We'll use podman-compose with an OpenRC service wrapper.
Alpine uses OpenRC, not systemd. So instead of quadlets we'll use podman-compose with an OpenRC service wrapper.
## Install Podman
## Install podman
```sh
apk update
@@ -253,14 +247,14 @@ rc-update add podman
rc-service podman start
```
## Create Directory Structure
## Create the directory structure
```sh
mkdir -p /srv/tranquil-pds/{data,config}
mkdir -p /srv/tranquil-pds/data/{postgres,blobs,backups,certs,acme}
```
## Clone Repository and Build Images
## Clone the repo and build images
```sh
cd /opt
@@ -270,7 +264,7 @@ podman build -t tranquil-pds:latest .
podman build -t tranquil-pds-frontend:latest ./frontend
```
## Create Environment File
## Create an environment file
```sh
cp /opt/tranquil-pds/.env.example /srv/tranquil-pds/config/tranquil-pds.env
@@ -282,7 +276,7 @@ Edit `/srv/tranquil-pds/config/tranquil-pds.env` and fill in your values. Genera
openssl rand -base64 48
```
## Set Up Compose and nginx
## Set up compose and nginx
Copy the production compose and nginx configs:
```sh
@@ -297,13 +291,13 @@ Edit `/srv/tranquil-pds/docker-compose.yml` to adjust paths if needed:
Edit `/srv/tranquil-pds/config/nginx.conf` to update cert paths:
- Change `/etc/nginx/certs/live/${PDS_HOSTNAME}/` to `/etc/nginx/certs/`
## Create OpenRC Service
## Create OpenRC service
```sh
cat > /etc/init.d/tranquil-pds << 'EOF'
#!/sbin/openrc-run
name="tranquil-pds"
description="Tranquil PDS AT Protocol PDS (containerized)"
description="Tranquil PDS AT Protocol PDS"
command="/usr/bin/podman-compose"
command_args="-f /srv/tranquil-pds/docker-compose.yml up"
command_background=true
@@ -331,7 +325,7 @@ EOF
chmod +x /etc/init.d/tranquil-pds
```
## Initialize Services
## Initialize services
Start services:
```sh
@@ -349,7 +343,7 @@ DB_IP=$(podman inspect tranquil-pds-db-1 --format '{{.NetworkSettings.Networks.t
DATABASE_URL="postgres://tranquil_pds:$DB_PASSWORD@$DB_IP:5432/pds" sqlx migrate run --source /opt/tranquil-pds/migrations
```
## Obtain Wildcard SSL Certificate
## Obtain wildcard SSL cert
User handles are served as subdomains (eg. `alice.pds.example.com`), so you need a wildcard certificate. Wildcard certs require DNS-01 validation.
@@ -381,13 +375,13 @@ ln -sf /srv/tranquil-pds/data/certs/live/pds.example.com/privkey.pem /srv/tranqu
rc-service tranquil-pds restart
```
## Enable Service at Boot
## Enable service at boot time
```sh
rc-update add tranquil-pds
```
## Configure Firewall
## Configure firewall if you're into that sort of thing
```sh
apk add iptables ip6tables
@@ -409,7 +403,7 @@ rc-update add ip6tables
/etc/init.d/ip6tables save
```
## Certificate Renewal
## Cert renewal
Add to root's crontab (`crontab -e`):
```
@@ -418,16 +412,16 @@ Add to root's crontab (`crontab -e`):
---
# Verification and Maintenance
# Verification and maintenance
## Verify Installation
## Verify installation
```sh
curl -s https://pds.example.com/xrpc/_health | jq
curl -s https://pds.example.com/.well-known/atproto-did
```
## View Logs
## View logs
**Debian:**
```bash
@@ -462,7 +456,7 @@ Alpine:
rc-service tranquil-pds restart
```
## Backup Database
## Backup database
**Debian:**
```bash
@@ -474,7 +468,7 @@ podman exec tranquil-pds-db pg_dump -U tranquil_pds pds > /var/backups/pds-$(dat
podman exec tranquil-pds-db-1 pg_dump -U tranquil_pds pds > /var/backups/pds-$(date +%Y%m%d).sql
```
## Custom Homepage
## Custom homepage
The frontend container serves `homepage.html` as the landing page. To customize it, either:

46
docs/install-debian.md
View File

@@ -1,23 +1,26 @@
# Tranquil PDS Production Installation on Debian
# Tranquil PDS production installation on debian
This guide covers installing Tranquil PDS on Debian 13.
This guide covers installing Tranquil PDS on Debian.
It is a "compile the thing on the server itself" -style guide.
This cop-out is because Tranquil isn't built and released via CI as of yet.
## Prerequisites
- A VPS with at least 2GB RAM
- Disk space for blobs (depends on usage; plan for ~1GB per active user as a baseline)
- A server :p
- Disk space enough for blobs (depends on usage; plan for ~1GB per active user as a baseline)
- A domain name pointing to your server's IP
- A wildcard TLS certificate for `*.pds.example.com` (user handles are served as subdomains)
- Root or sudo access
- Root/sudo/doas access
## System Setup
## System setup
```bash
apt update && apt upgrade -y
apt install -y curl git build-essential pkg-config libssl-dev
```
## Install Rust
## Install rust
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
@@ -38,7 +41,7 @@ sudo -u postgres psql -c "CREATE DATABASE pds OWNER tranquil_pds;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE pds TO tranquil_pds;"
```
## Create Blob Storage Directories
## Create blob storage directories
```bash
mkdir -p /var/lib/tranquil/blobs /var/lib/tranquil/backups
@@ -54,7 +57,7 @@ export PATH="$HOME/.deno/bin:$PATH"
echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
```
## Clone and Build Tranquil PDS
## Clone and build Tranquil PDS
```bash
cd /opt
@@ -66,14 +69,6 @@ cd ..
cargo build --release
```
## Install sqlx-cli and Run Migrations
```bash
cargo install sqlx-cli --no-default-features --features postgres
export DATABASE_URL="postgres://tranquil_pds:your-secure-password@localhost:5432/pds"
sqlx migrate run
```
## Configure Tranquil PDS
```bash
@@ -87,7 +82,7 @@ Edit `/etc/tranquil-pds/tranquil-pds.env` and fill in your values. Generate secr
openssl rand -base64 48
```
## Install Frontend Files
## Install frontend files
```bash
mkdir -p /var/www/tranquil-pds
@@ -95,7 +90,7 @@ cp -r /opt/tranquil-pds/frontend/dist/* /var/www/tranquil-pds/
chown -R www-data:www-data /var/www/tranquil-pds
```
## Create Systemd Service
## Create systemd service
```bash
useradd -r -s /sbin/nologin tranquil-pds
@@ -127,7 +122,7 @@ systemctl enable tranquil-pds
systemctl start tranquil-pds
```
## Install and Configure nginx
## Install and configure nginx
```bash
apt install -y nginx certbot python3-certbot-nginx
@@ -264,7 +259,7 @@ nginx -t
systemctl reload nginx
```
## Obtain Wildcard SSL Certificate
## Obtain a wildcard SSL cert
User handles are served as subdomains (eg., `alice.pds.example.com`), so you need a wildcard certificate.
@@ -289,7 +284,7 @@ After obtaining the cert, reload nginx:
systemctl reload nginx
```
## Configure Firewall
## Configure firewall if you're into that sort of thing
```bash
apt install -y ufw
@@ -299,7 +294,7 @@ ufw allow 443/tcp
ufw enable
```
## Verify Installation
## Verify installation
```bash
systemctl status tranquil-pds
@@ -323,16 +318,17 @@ cargo build --release
systemctl stop tranquil-pds
cp target/release/tranquil-pds /usr/local/bin/
cp -r frontend/dist/* /var/www/tranquil-pds/
DATABASE_URL="postgres://tranquil_pds:your-secure-password@localhost:5432/pds" sqlx migrate run
systemctl start tranquil-pds
```
Tranquil should auto-migrate if there are any new migrations to be applied to the db, so you don't need to worry.
Backup database:
```bash
sudo -u postgres pg_dump pds > /var/backups/pds-$(date +%Y%m%d).sql
```
## Custom Homepage
## Custom homepage
Drop a `homepage.html` in `/var/www/tranquil-pds/` and it becomes your landing page. Account dashboard is at `/app/` so you won't break anything.

4
docs/install-kubernetes.md
View File

@@ -1,4 +1,4 @@
# Tranquil PDS on Kubernetes
# Tranquil PDS on kubernetes
If you're reaching for kubernetes for this app, you're experienced enough to know how to spin up:
@@ -19,7 +19,7 @@ and more, check the .env.example.
Health check: `GET /xrpc/_health`
## Custom Homepage
## Custom homepage
Mount a ConfigMap with your `homepage.html` into the container's frontend directory and it becomes your landing page. Go nuts with it. Account dashboard is at `/app/` so you won't break anything.

4
frontend/public/homepage.html
View File

@@ -420,8 +420,8 @@
and alerts, granular OAuth scopes with human-readable descriptions,
app passwords with configurable permissions (read-only, post-only,
or custom scopes), account delegation with permission levels and
audit logging, and a built-in web UI for account management, OAuth
consent, repo browsing, and admin.
audit logging, and a built-in web UI for account management,
repo browsing, and admin.
</p>
</div>
</section>