this repo has no description
lewis.moe
1# Tranquil PDS Production Installation on Debian
2This guide covers installing Tranquil PDS on Debian 13.
3
4## Prerequisites
5- A VPS with at least 2GB RAM and 20GB disk
6- A domain name pointing to your server's IP
7- A wildcard TLS certificate for `*.pds.example.com` (user handles are served as subdomains)
8- Root or sudo access
9## 1. System Setup
10```bash
11apt update && apt upgrade -y
12apt install -y curl git build-essential pkg-config libssl-dev
13```
14## 2. Install Rust
15```bash
16curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
17source ~/.cargo/env
18rustup default stable
19```
20This installs the latest stable Rust.
21## 3. Install postgres
22```bash
23apt install -y postgresql postgresql-contrib
24systemctl enable postgresql
25systemctl start postgresql
26sudo -u postgres psql -c "CREATE USER tranquil_pds WITH PASSWORD 'your-secure-password';"
27sudo -u postgres psql -c "CREATE DATABASE pds OWNER tranquil_pds;"
28sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE pds TO tranquil_pds;"
29```
30## 4. Install minio
31```bash
32curl -O https://dl.min.io/server/minio/release/linux-amd64/minio
33chmod +x minio
34mv minio /usr/local/bin/
35mkdir -p /var/lib/minio/data
36useradd -r -s /sbin/nologin minio-user
37chown -R minio-user:minio-user /var/lib/minio
38cat > /etc/default/minio << 'EOF'
39MINIO_ROOT_USER=minioadmin
40MINIO_ROOT_PASSWORD=your-minio-password
41MINIO_VOLUMES="/var/lib/minio/data"
42MINIO_OPTS="--console-address :9001"
43EOF
44cat > /etc/systemd/system/minio.service << 'EOF'
45[Unit]
46Description=MinIO Object Storage
47After=network.target
48[Service]
49User=minio-user
50Group=minio-user
51EnvironmentFile=/etc/default/minio
52ExecStart=/usr/local/bin/minio server $MINIO_VOLUMES $MINIO_OPTS
53Restart=always
54LimitNOFILE=65536
55[Install]
56WantedBy=multi-user.target
57EOF
58systemctl daemon-reload
59systemctl enable minio
60systemctl start minio
61```
62Create the buckets (wait a few seconds for minio to start):
63```bash
64curl -O https://dl.min.io/client/mc/release/linux-amd64/mc
65chmod +x mc
66mv mc /usr/local/bin/
67mc alias set local http://localhost:9000 minioadmin your-minio-password
68mc mb local/pds-blobs
69mc mb local/pds-backups
70```
71## 5. Install valkey
72```bash
73apt install -y valkey
74systemctl enable valkey-server
75systemctl start valkey-server
76```
77## 6. Install deno (for frontend build)
78```bash
79curl -fsSL https://deno.land/install.sh | sh
80export PATH="$HOME/.deno/bin:$PATH"
81echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
82```
83## 7. Clone and Build Tranquil PDS
84```bash
85cd /opt
86git clone https://tangled.org/lewis.moe/bspds-sandbox tranquil-pds
87cd tranquil-pds
88cd frontend
89deno task build
90cd ..
91cargo build --release
92```
93## 8. Install sqlx-cli and Run Migrations
94```bash
95cargo install sqlx-cli --no-default-features --features postgres
96export DATABASE_URL="postgres://tranquil_pds:your-secure-password@localhost:5432/pds"
97sqlx migrate run
98```
99## 9. Configure Tranquil PDS
100```bash
101mkdir -p /etc/tranquil-pds
102cp /opt/tranquil-pds/.env.example /etc/tranquil-pds/tranquil-pds.env
103chmod 600 /etc/tranquil-pds/tranquil-pds.env
104```
105Edit `/etc/tranquil-pds/tranquil-pds.env` and fill in your values. Generate secrets with:
106```bash
107openssl rand -base64 48
108```
109## 10. Create Systemd Service
110```bash
111useradd -r -s /sbin/nologin tranquil-pds
112cp /opt/tranquil-pds/target/release/tranquil-pds /usr/local/bin/
113mkdir -p /var/lib/tranquil-pds
114cp -r /opt/tranquil-pds/frontend/dist /var/lib/tranquil-pds/frontend
115chown -R tranquil-pds:tranquil-pds /var/lib/tranquil-pds
116cat > /etc/systemd/system/tranquil-pds.service << 'EOF'
117[Unit]
118Description=Tranquil PDS - AT Protocol PDS
119After=network.target postgresql.service minio.service
120[Service]
121Type=simple
122User=tranquil-pds
123Group=tranquil-pds
124EnvironmentFile=/etc/tranquil-pds/tranquil-pds.env
125Environment=FRONTEND_DIR=/var/lib/tranquil-pds/frontend
126ExecStart=/usr/local/bin/tranquil-pds
127Restart=always
128RestartSec=5
129[Install]
130WantedBy=multi-user.target
131EOF
132systemctl daemon-reload
133systemctl enable tranquil-pds
134systemctl start tranquil-pds
135```
136## 11. Install and Configure nginx
137```bash
138apt install -y nginx certbot python3-certbot-nginx
139cat > /etc/nginx/sites-available/tranquil-pds << 'EOF'
140server {
141 listen 80;
142 listen [::]:80;
143 server_name pds.example.com;
144 location / {
145 proxy_pass http://127.0.0.1:3000;
146 proxy_http_version 1.1;
147 proxy_set_header Upgrade $http_upgrade;
148 proxy_set_header Connection "upgrade";
149 proxy_set_header Host $host;
150 proxy_set_header X-Real-IP $remote_addr;
151 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
152 proxy_set_header X-Forwarded-Proto $scheme;
153 proxy_read_timeout 86400;
154 }
155}
156EOF
157ln -s /etc/nginx/sites-available/tranquil-pds /etc/nginx/sites-enabled/
158rm -f /etc/nginx/sites-enabled/default
159nginx -t
160systemctl reload nginx
161```
162## 12. Obtain Wildcard SSL Certificate
163User handles are served as subdomains (e.g., `alice.pds.example.com`), so you need a wildcard certificate.
164
165Wildcard certs require DNS-01 validation. If your DNS provider has a certbot plugin:
166```bash
167apt install -y python3-certbot-dns-cloudflare
168certbot certonly --dns-cloudflare \
169 --dns-cloudflare-credentials /etc/cloudflare.ini \
170 -d pds.example.com -d '*.pds.example.com'
171```
172
173For manual DNS validation (works with any provider):
174```bash
175certbot certonly --manual --preferred-challenges dns \
176 -d pds.example.com -d '*.pds.example.com'
177```
178Follow the prompts to add TXT records to your DNS. Note: manual mode doesn't auto-renew.
179
180After obtaining the cert, update nginx to use it and reload.
181## 13. Configure Firewall
182```bash
183apt install -y ufw
184ufw allow ssh
185ufw allow 80/tcp
186ufw allow 443/tcp
187ufw enable
188```
189## 14. Verify Installation
190```bash
191systemctl status tranquil-pds
192curl -s https://pds.example.com/xrpc/_health | jq
193curl -s https://pds.example.com/.well-known/atproto-did
194```
195## Maintenance
196View logs:
197```bash
198journalctl -u tranquil-pds -f
199```
200Update Tranquil PDS:
201```bash
202cd /opt/tranquil-pds
203git pull
204cd frontend && deno task build && cd ..
205cargo build --release
206systemctl stop tranquil-pds
207cp target/release/tranquil-pds /usr/local/bin/
208cp -r frontend/dist /var/lib/tranquil-pds/frontend
209DATABASE_URL="postgres://tranquil_pds:your-secure-password@localhost:5432/pds" sqlx migrate run
210systemctl start tranquil-pds
211```
212Backup database:
213```bash
214sudo -u postgres pg_dump pds > /var/backups/pds-$(date +%Y%m%d).sql
215```
216
217## Custom Homepage
218
219Drop a `homepage.html` in `/var/lib/tranquil-pds/frontend/` and it becomes your landing page. Go nuts with it. Account dashboard is at `/app/` so you won't break anything.
220
221```bash
222cat > /var/lib/tranquil-pds/frontend/homepage.html << 'EOF'
223<!DOCTYPE html>
224<html>
225<head>
226 <title>Welcome to my PDS</title>
227 <style>
228 body { font-family: system-ui; max-width: 600px; margin: 100px auto; padding: 20px; }
229 </style>
230</head>
231<body>
232 <h1>Welcome to my secret PDS</h1>
233 <p>This is a <a href="https://atproto.com">AT Protocol</a> Personal Data Server.</p>
234 <p><a href="/app/">Sign in</a> or learn more at <a href="https://bsky.social">Bluesky</a>.</p>
235</body>
236</html>
237EOF
238```