From a83a67d219acae4cf22838dc04132c080d4474a7 Mon Sep 17 00:00:00 2001 From: lewis Date: Wed, 11 Feb 2026 18:16:38 +0200 Subject: [PATCH] chore: small md file updates --- README.md | 22 ++++----- docs/install-containers.md | 90 ++++++++++++++++------------------- docs/install-debian.md | 46 ++++++++---------- docs/install-kubernetes.md | 4 +- frontend/public/homepage.html | 4 +- 5 files changed, 76 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 4f52301..656a248 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/install-containers.md b/docs/install-containers.md index 160c740..1e9abb3 100644 --- a/docs/install-containers.md +++ b/docs/install-containers.md @@ -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: diff --git a/docs/install-debian.md b/docs/install-debian.md index 7399af9..7d8900d 100644 --- a/docs/install-debian.md +++ b/docs/install-debian.md @@ -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. diff --git a/docs/install-kubernetes.md b/docs/install-kubernetes.md index 1e13948..44435df 100644 --- a/docs/install-kubernetes.md +++ b/docs/install-kubernetes.md @@ -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. diff --git a/frontend/public/homepage.html b/frontend/public/homepage.html index 7348c50..40354d6 100644 --- a/frontend/public/homepage.html +++ b/frontend/public/homepage.html @@ -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.