85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
# atproto-pds-ansible
|
|
|
|
Ansible playbook for deploying a self-hosted [Bluesky PDS](https://github.com/bluesky-social/pds) with Caddy (TLS) and Watchtower (auto-updates).
|
|
|
|
## What it deploys
|
|
|
|
- **PDS** — Bluesky Personal Data Server (`ghcr.io/bluesky-social/pds:0.4`)
|
|
- **Caddy** — Reverse proxy with automatic TLS via Let's Encrypt
|
|
- **Watchtower** — Pulls new PDS image versions hourly and recreates containers
|
|
|
|
## Requirements
|
|
|
|
- A server running Ubuntu 20.04/22.04/24.04 or Debian 11/12/13
|
|
- SSH access as the `sysadmin` user (with sudo privileges)
|
|
- A domain pointed at the server (A record for the hostname + wildcard `*.` subdomain for handles)
|
|
- Ports 80 and 443 open to the internet
|
|
- Ansible installed locally
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
cp inventory.yml.example inventory.yml # set your server IP
|
|
cp vars/main.yml.example vars/main.yml # set your hostname and admin email
|
|
```
|
|
|
|
Edit `inventory.yml`:
|
|
|
|
```yaml
|
|
all:
|
|
hosts:
|
|
pds:
|
|
ansible_host: 203.0.113.10
|
|
```
|
|
|
|
Edit `vars/main.yml`:
|
|
|
|
```yaml
|
|
pds_hostname: bsky.example.com
|
|
pds_admin_email: you@example.com
|
|
```
|
|
|
|
## Deploy
|
|
|
|
```bash
|
|
ansible-playbook playbook.yml
|
|
```
|
|
|
|
## What it does
|
|
|
|
**First run:** the official [PDS installer](https://github.com/bluesky-social/pds/blob/main/installer.sh) bootstraps Docker, generates secrets, and creates the initial database. Ansible then templates `compose.yaml` and `Caddyfile` over the installer's defaults and runs `docker compose up -d`.
|
|
|
|
**Subsequent runs:** the installer is skipped (guarded by `account.sqlite`). Ansible only applies changes if the templates have changed. `docker compose up -d` is a no-op when nothing changed.
|
|
|
|
## Variables
|
|
|
|
| Variable | Required | Default | Description |
|
|
|---|---|---|---|
|
|
| `pds_hostname` | yes | — | Public DNS name for the PDS |
|
|
| `pds_admin_email` | yes | — | Admin contact email (used by Caddy for Let's Encrypt) |
|
|
| `pds_data_dir` | no | `/pds` | Data directory (must be `/pds` — the installer enforces this) |
|
|
| `pds_image_tag` | no | `0.4` | PDS Docker image tag |
|
|
|
|
## Auto-updates
|
|
|
|
Watchtower checks every hour (`WATCHTOWER_POLL_INTERVAL=3600`) for new `0.4.x` images on `ghcr.io/bluesky-social/pds:0.4`. When a new image is found, it pulls it and recreates the container. Old images are cleaned up automatically.
|
|
|
|
## Post-deploy
|
|
|
|
Check that the PDS is healthy:
|
|
|
|
```bash
|
|
curl https://your-hostname/xrpc/_health
|
|
```
|
|
|
|
Create an account:
|
|
|
|
```bash
|
|
pdsadmin account create
|
|
```
|
|
|
|
## Notes
|
|
|
|
- `pds.env` (containing JWT secret, admin password, PLC rotation key) is generated by the installer and not managed by Ansible. Edit it directly on the server to add SMTP or change settings.
|
|
- The installer creates a `pds.service` systemd unit. It's left in place — it just runs `docker compose up -d` on boot. Docker's `restart: unless-stopped` policy also handles this independently.
|