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